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Foreword 



If you have a solid understanding of machine language, Pascal, or 
C, you'll find Advanced Programming Tccluiiques for the Apple lies 
Toolbox invaluable in helping you to improve your Apple IlGS pro- 
gramming skills. This book examines in detail the structures and 
procedures necessary to make the Apple IlGS perform for you. Al- 
though the machine has been available for over a year and a half, 
the programming market for the Apple IlGS is still wide open. Pro- 
grams that take full advantage of the machine's capabilities have 
only begun to appear. 

"This book is not for the beginner," the authors warn early in 
the first chapter. But intermediate- to advanced-level programmers 
will find Advanced Programming Techniques for the Apple IlGS Tool- 
box packed with solid information on this fast-selling machine. This 
book delves into the intricacies of the powerful set of libraries 
known collectively as the Toolbox. 

The program examples given here are ready to be merged with 
your own program code, giving your programs greater flexibility 
within the IlGS operating system. Mirroring the flexibility of the 
machine, this book provides a nonlinear approach that allows you 
to turn to your area of immediate interest, begin learning the things 
you need to know, and produce the program you're trying to write, 
in your choice of languages. Along the way, you'll learn about the 
other languages and the inner workings of the operating system. 

Inside this book is information covering DeskTop applications, 
the mouse, pull-down menus, windows, dialog boxes, controls, 
special applications like interrupts, and the use of ProDOS 16. 
You'll also find a condensed version of Apple's Human Interface 
Guidelines as well appendices packed with technical information. 

Advanced Programming Techniques for the Apple IIgs Toolbox is 
a treasure trove of inside information of all kinds. You'll value its 
insights into this exciting machine. This is the book every interme- 
diate- to advanced-level programmer needs to enhance his or her 
programming skills. 






Chapter 1 

Introduction 



To use this book, you should 
have an assembler, or you 
should have a Pascal or C lan- 
guage compiler. The software 
mentioned in this book are 
the APW [Apple Programmer's 
Workshop) C and machine lan- 
guage development kit and 
TML Pascal. These programs 
and their associated utilities 
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are available at the addresses given on the copyright page. 

This book is intended to be a complement to COMPUTERS 
Mastering the Apple IIGS Toolbox, a tutorial on programming the 
Apple IIGS Toolbox. This book goes more deeply into the intrica- 
cies of using this powerful set of libraries to put a professional pol- 
ish on applications. It's both a reference and a book of advice on 
designing and building solid programs in machine language, C, and 
Pascal, 

It's assumed that you've read COMPUTEVs Mastering the Apple 
Hgs Toolbox, or you're already a highly skilled programmer of the 
Apple IIGS. If so, you're ready to begin a challenging and enjoyable 
programming adventure. Keep in mind that this book is not for the 
beginner. 

If you haven't read COMPUTED Mastering the Apple llGS Tool- 
box, or one of the other worthy introductory texts on this computer, 
you'd be wise to purchase one and read it before venturing further 
into this book. 

This book also assumes you have an Apple llGS handy to test 
the routines. Your computer should have at least 512K of RAM, 
with one or two disk drives. A color monitor is more interesting to 
look at, but it is not a necessity. 

What This Book Is About 

This book provides programming advice for the Apple IIGS in three 
different languages; machine language, Pascal, and C. A solid un- 
derstanding of one or more of these programming languages is re- 
quired to be able to grasp the concepts in this book. You can't 
program the llGS without them. 

Although the Apple IIGS has the same, decade-old, proven 
BASIC as its ancestors, Applesoft BASIC is not an appropriate lan- 
guage for writing application programs, In fact, the only way to ac- 
cess the advanced techniques of the Apple IIGS from BASIC is by 
using in-line machine language, a technique that is not recom- 
mended, even for the most venturesome programmers. 

If you are a BASIC programmer, you might be interested to 
know that two new BASICs were announced for the Apple IIGS as 
this book was being prepared. One, from TML Systems of Jackson- 
ville, Florida, and a second from Apple. (There may be more BASICs 
forthcoming from other developers.) These BASICs are in their 
"beta test" stage at this writing (which means they are not yet 
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ready for general release; they have too many bugs). 

The Toolbox. The key to programming the Apple IlGS is its 
Toolbox. The Toolbox contains hundreds of routines and functions 
that provide the core of programming, Programming the Toolbox is 
a central part of this book. And examples for programming the 
Toolbox are provided in C, Pascal, and machine language. 

This book is not intended to be a Toolbox tutorial. Instead, it 
was written to acquaint readers, programmers, and Apple enthusi- 
asts with the finer aspects of programming the machine. 

The scope of this book is limited to these general areas: the 
DeskTop, graphics, low-level tools, and other rarely discussed as- 
pects of the Apple IlGS. These areas are well covered and offer an 
in-depth look at the inner workings of the computer. 

Who This Book Is For 

This book will benefit Apple 1IG5 owners who understand machine 
language, Pascal, or C. Any one of these languages will do, and, 
after reading a few chapters, you'll probably learn more about the 
others. 

As mentioned above, you'll need an Apple IlGS with at least 
512K. The IlGS is currently being sold with 256K. Even Apple ad- 
mits this isn't enough. Producing a 256K machine was a decision 
made to keep the base unit as inexpensive as possible. Another de- 
cision based on economy was the choice of the 65816 micro- 
processor, which is only rated at 2.8 MHz. The engineers could 
have used a faster chip, but it would have added $100 to the price 
of the computer. 

It's recommended that when you buy a memory card for your 
IlGS, you pack it full of memory. Memory is relatively inexpensive. 
For the cost of 16K of RAM in 1980 you can easily put over 1024K 
(one megabyte) of RAM into your IlGS. 

Finally, this book is for anyone excited about the Apple JIGS. 
It's been over a year and a half since the machine was introduced. 
Exciting and interesting programs are only starting to appear. With 
the knowledge you'll gain from this book, you'll soon add your 
own programs to the growing list of applications for the Apple 
IlGS. 

Unlike COMPUTEI's Mastering the Apple Has Toolbox, this book 
doesn't rely upon complete programs to convey ideas. Instead, only 
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small program examples and snippets of code are used. It's as- 
sumed you'll be able to put the example pieces together in your 
own way when creating applications. The examples listed in this 
book all work and will function in any program you write. 

Though you may be tempted to dive into programming with- 
out preparation, you'll gain more if you read the text dealing with 
each program example before cutting and pasting code. While it 
looks easy and simple, the Toolbox routines have interdependent 
relationships with each other. To understand how one tool relies 
upon another, read the text before and after an example. Then you 
should be able to adapt it successfully to your use. 

This book is half reference and half tutorial. The "refertorial" 
approach makes this book modular. You can start reading at any 
point. For example, if you'd like to know how to put a custom icon 
in one of your dialog boxes, turn to the chapter on dialog boxes, 
and you'll find an example. Replace the graphic in the example 
with your own, and you'll have a custom icon. This entire book 

works that way. 

On a larger scale, this book is divided into four major parts, 
each part concentrating on a specific area of programming the Ap- 
ple IlGS and the Toolbox. Each part is further broken down into in- 
dividual areas that cover specific topics. Within each area are 
individual examples and routines you can use to help you under- 
stand and program the Apple IlGS. 

You can read any section that interests you, provided that you 
have taken the time to understand the fundamentals. If any infor- 
mation overlaps or is covered elsewhere, you'll be directed to the 
proper part and section. Most of the groundwork is covered in this, 
the first section, so naturally, you should take the time to read 
through the introductory material. When you're finished, you may 
proceed through the book at your own pace and in any order. 

The book is divided as follows: 
• The early chapters offer a general introduction. When you're fin- 
ished reading them, you'll understand how information is pre- 
sented in this book, For example, one chapter demonstrates how 
Toolbox routines are documented in this book for all three pro- 
gramming languages. You may skim that section and return to 
read it in detail if a concept in a later chapter confuses you. You'll 
also find a great deal of interesting trivia and general background 
information in this section. 
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• The middle portion of the book covers DeskTop applications and 
using the mouse. It details DeskTop programs, pull-down menus, 
windows, dialog boxes, and controls. This section covers many 
concepts unique to the IlGS. Don't be surprised if you find your- 
self referring to this part of the book often. 

* The final chapters go into detail on special applications — those fea- 
tures of the Apple IlGS that don't have a category of their own. 
This part covers such advanced topics such as interrupts and desk 
accessories. At the end of this section is a chapter on ProDOS 16. 
Though unrelated to the Toolbox, ProDOS is as much a part of the 
Apple IlGS as anything mentioned so far. Loading and saving files 
from and to disk and other file-management techniques are men- 
tioned in the ProDOS chapter. 

■ The Appendices provide a reference to the first part of the book. 
You'll find a version of Apple's Human Interface Guidelines in 
Appendix A. While not an exact duplicate, this version highlights 
the most important parts of the Human Interface Guidelines, en- 
suring that your programs will fall in line with Apple's recom- 
mendations for all DeskTop applications. 

Interesting trivia surrounding the Apple IlGS is just now rising 
to the surface. Where appropriate, comments and insights have 
been included in the main body of the text, but when they are tan- 
gential or circumstantial to the topic at hand, they will be set aside 
in boxes. They were included to give a better understanding of Ap- 
ple IlGS hardware and software construction. 

Conventions Used in This Book 

Every effort has been made to maintain notations and conventions 
used in COMPUTEI's Mastering the Apple IlGS Toolbox. For example, 
the majority of the numbers you'll see in this book are in hexadeci- 
mal (base- 16) notation. All hexadecimal numbers are preceded by a 
$ {dollar sign), and they contain the numbers 1-9 and the capital 
letters A-F, which stand for the values 10-15. 

There are three types of hexadecimal numbers used in this 
book: bytes, words, and long words. 



A byte value is a two-digit hexadecimal number ranging from 
$00 through $FF (0-255 decimal). A word value is a four-digit 
hexadecimal number ranging from $0000 through $FFFF (0-65535 
decimal). Words are composed of two bytes, the most significant 
byte (MSB) and the least significant byte (LSB). In the word value 
$FACE, $FA is the MSB and $CE is the LSB. 

Long words are new to the Apple II. A long word is an eight- 
digit hexadecimal number equivalent to two words or four bytes. It 
ranges in value from $00000000 through SFFFFFFFF (0 through 
4,294,967,295 decimal). Long words are composed of two words — 
the high-order word and the low-order word. In the long-word 
value S00E100A8, $00E1 is the high-order word, and S00A8 is the 
low-order word. Long words are primarily used in the Apple IlGS 
to denote memory locations. Refer to the section on memory ad- 
dressing in the next chapter for details. 

Though not a type of number (or size), the Toolbox uses logi- 
cal or Boolean, values to represent the true or false result of certain 
operations. A true value is any value not equal to 0. Commonly, 
true is set to the hexadecimal word value of $8000. A false value is 
0. 

Logical True = $8000 or any nonzero value 
Logical False = $0000 

When the Toolbox returns a logical true or false value, the ac- 
tual numbers returned are as listed above. As might be expected, 
there are times when the computer breaks this rule and returns 
for true and a nonzero value for false. When this happens, a note 
will be provided to warn you about it. 

One final convention concerns the program listings in this 
book. Line numbers are included with all program listings above a 
certain size. Unless specified, the line numbers are not to be en- 
tered (when you type in the examples) or considered as part of the 
source. The line numbers are intended for use as references from 
the text. Again, where there are exceptions, they will be noted. 
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Books Worthy of Note 

At this writing, there are few books on the subject of programming 
the Apple IlGS. However, the books listed below are recommended 
for anyone interested in programming the Apple IlGS: 

• COMPUTEI's Mastering the Apple IlGS Toolbox, Dan Gookin and 
Morgan Davis (1987, COMPUTE! Publications, ISBN 0-87455- 
120-X). 

• COMPUTEI's Apple IlGS Machine Language for Beginners, Roger 
Wagner (1987, COMPUTE! Publications, ISBN 0-87455-097-1), 
Roger wrote the definitive machine language book years ago. This 
book carries on the tradition. 

• COMPUTEI's Guide to Sound and Graphics on the Apple IlGS, Wil- 
liam B. Sanders (1987, COMPUTE! Publications. ISBN 0-87455- 
096-3). Though lacking extensive Toolbox programming examples, 
this book contains a wealth of information on fundamental Apple 
IlGS sound and graphics. 

• Apple IlGS Technical Reference, Michael Fischer (1986, 1987; 
McGraw-Hill; ISBN 0-07-881009-4). One of the first books to ap- 
pear on the market, this book is an excellent hardware and soft- 
ware reference to the Apple IlGS. Some of the material is 
outdated, but it's still worthy. 

• Programming the 65816, David Eyes and Ron Lichty (1986, Pren- 
tice-Hall, ISBN 0-89303-789-3), The ultimate reference to the 
65816, with programming examples and the best command refer- 
ence of any microprocessor book. 



Chapter 2 



Programming 
Subtleties 



The purpose of this chapter is 
to acquaint you with some 
things you should know before 
attempting to program the Ap- 
ple IlGS. This information — 
background material, plus some 
interesting tidbits — was gath- 
ered over a long period of time 
during visits to the offices of 
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Apple Computers and through research in virtually every book 
available on this machine. The material listed here is the distillation 
of this research. (For more detailed explanations, refer to COM- 
PUTED Mastering the Apple lies Toolbox.) 

How the Apple IlGS Is Different from Other Apples 

The Apple II is an "ancient" and honored computer, with a re- 
spectable lineage dating back just a little over ten years. Generally 
speaking, the Apple lies is simply the latest incarnation of the Ap- 
ple II, It has a faster and more powerful microprocessor, better 
graphics, and advanced sound capabilities, but it can run Apple II 
software and accommodate Apple II hardware. It also has a tool set 
of programming routines that allow it to mimic its distant cousin, 
the Macintosh. 

In fact, the Apple 1IGS is actually one step closer to the Macin- 
tosh computer than simply an improvement on the older Apple II 
design. While the computer is still compatible, the DeskTop exten- 
sions, the graphics, and the sound found in the Toolbox routines 
separate the Apple IlGS from the rest of the Apple II family. 

The Apple IlGS is an evolutionary computer in terms of design 
and implementation. It's difficult to document. The machine's oper- 
ation is different now from its operation a few months ago. This 
implies that a shortcut or trick you learn today might not work 
tomorrow. 

Apple is constantly working on the IlGS. Internal modifications 
are being made, and the firmware and tool sets are constantly be- 
ing upgraded and modified. Because of this, a warning is offered: 
Do not stray from the standard. 

The Macintosh is another evolutionary machine. The first Mac- 
intosh, introduced in 1984, could not compare to the powerful ma- 
chines Apple makes today. While the Apple IlGS probably won't 
have the same expensive upgrades the Mac had, it will share the 
technological advances of its distant relative. Apple has assured its 
developers that as long as they stick to the standards, their pro- 
grams will run on all future releases of Apple II computers. 

A good example of programmers not sticking to the standards 
is in the area of the super-hi-res graphics display. Apple has re- 
peatedly warned against finding the screen's secret location in 
memory. Why? Because it may change in the future. The proper 
way to use the graphics screen is through the Toolbox. Yet, some 
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developers consider the Toolbox routines slow. For this reason, 
they prefer to access the screen directly so their programs will work 
faster. By doing so, they run the risk that in the future they may 
not work at all. 

As long as you adhere to the techniques and programming ex- 
amples used in this book, you can be assured that your applica- 
tions will have a long and healthy life — as long as the Apple IT 
series stands. According to Apple, it will last forever. 



Here is an abridged history of the Apple computer: The first 
Apple computer, the Apple 1. was actually a circuit-board kit 
that sold for $666.66 in July 1976. 

The Apple II, which came in a case with a keyboard and 
power supply, was unveiled at the West Coast Computer Faire 
in April 1977. It came with its own BASIC, 4K of memory, 
color graphics, and game paddles. The Apple II was available 
for sale to the general public in June of 1977 for $1,298. 

In June 1979, the Apple 11+ was introduced. It had an 
improved ROM, could handle up to 48K of RAM, and retailed 
for $1,195. In October of that year, the software program 
VisiCalc became available. 

The Apple He was presented in January 1983. It came 
with 64K, which could be upgraded to 128K. Also included 
was a lowercase keyboard option, as well as an 80-column 
screen. The lie retailed for $1,395. 

The Apple lie portable was introduced in April 1984. A 
marketing genius came up with the slogan "Apple 11 Forever." 

In September 1986, the Apple IlGS was introduced. Nine 
years after the first Apple, the IlGS was priced at $999, came 
standard with 256K of memory, a keyboard, a mouse, and a 
mountain of potential. 



Graphics 

The Apple IlGS contains all the graphics modes of its predecessors, 
plus a new high-resolution graphics mode. The super-hi-res screen 
is used for all the IlGS graphics and provides a Macintosh-like envi- 
ronment. The responsibility for producing these graphics is given to 
the Video Graphics Controller (VGC) chip. 

The VGC has a big job. Not only does it control the super-hi- 
res graphics screen, it handles the older Apple II graphics modes. 
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as well as dealing with two different types of interrupts. The VGC 
allows the Apple IlGS with a color monitor to have a different text, 
background, and border colors. It also provides foreign language 
character sets and international video output (for European coun- 
tries). It's a remarkable piece of engineering. 

The following chart shows the Apple 1ICS text and graphics 
screens and their resolutions. The Apple He and He are both repre- 
sented by the He. The resolution is shown as horizontal pixels by 
vertical pixels. 

Colors H + ne Apple ncs 

2 (16 for IlGS only) * 

2(16 for lies only) 

16 

16 

6 

1 

16 



Graphics Mode Resolution 
Text screen 40 X 24 



80 X 24 
40 X 48 
80 X 48 

280 X 192 
560 X 192 
320 X 200 
640 X 200 



Text screen 
Lo res 

Double lo res 
Hi res 

Double hi res 
Super hi res 
Super hi res 

The 80-column text screen was available to Apple 11+ owners 
via a special 80-column card. However, with the introduction of 
the Apple He, and later the lie, the 80-column text format became 

standard. 

The lo-res mode displayed graphic "bricks" called pixels 
(though a pixel usually refers to a small dot). In the hires mode, 
the colors of the pixels and other graphics variations depended on 
a number of things, most of which are too specific to go into in this 
book. (A good book on the subject is COMPUTED Guide to Sound 
and Graphics on the Apple IlGS by William B. Sanders.) 

Super Hi Res 

This book is concerned with the super-hires screen on the Apple 
IlGS It has two modes: low and high resolution. The high-resolu- 
tion mode has a pixel resolution of 640 X 200. This mode provides 
four colors. However, by using a process known as dithering, more 
colors can be produced on the screen. Also, by altering certain 
attributes of the screen, up to 256 different colors can be produced 
on one super-hires screen. 
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Questions almost every computer owner asks are "Where is the 
screen in memory? Is it bitmapped?" 

As explained above, this knowledge will not come in handy. 
However, to be accommodating, a few secrets can be revealed. 

At this writing {it will almost certainly change), the super-hi- 
res graphics screen is located in memory bank $E1, at offset 
$2000. {Refer to the section on memory management later in this 
chapter for further explanation of this memory reference.) To acti- 
vate the screen from Applesoft BASIC, you can type the follow- 
ing (the bracket is the Applesoft prompt): 

]CALL -1B1 

That will put you in the monitor. Type the following to refer- 
ence memory bank $E1 (the asterisk is the monitor's prompt): 

•El/0000 

Now, activate the super-hi-res mode by putting the byte 
value SCI into memory location $C029, the New-video register: 

•C029:C1 

That will activate the super-hi-res screen, which implies that 
from here on you'll be typing "in the dark." Text will be invisi- 
ble. Sometimes a pretty pattern will appear on the screen. Other 
times, the data previously on the super-high-res screen can be 
seen. 

Now, any value poked into memory locations $2000-$9CFF 
will appear on the screen as a pixel, series of pixels, pattern, or 
color. For example, putting the value $00 into memory location 
$60BO might put a black dash near the middle of the screen: 

•60B0:0O 

You can experiment with your own values (within the proper 
range of $2000-$9CFF). When you want to return to normal, you 
must poke a value of $01 back into memory location $C029: 

•C029:l 

Or you can type Control-T followed by the RETURN key. 
Have fun, but remember the warnings. 
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The low-resolution mode of the super-hi-res screen has the 
same vertical resolution (200 pixels) but only half the horizontal 
resolution of the high-resolution mode. It does, however, have 
more colors— up to 16— chosen from over 4096 possibilities. By 
using dithering you can squeeze even more colors out of the low- 
resolution graphics mode. 

You might hear the 640 mode of the super-hi-res screen re- 
ferred to as "80 columns/' and the 320 mode as "40 columns." 
While this is entirely inaccurate, it does express the appearance of 
the two modes. In fact, by displaying text on the graphics screen 
using different fonts, your actual text-screen size varies from 16 
rows by 63 columns to 32 rows by 132 columns. (Text is displayed 
on this screen using a combination of the QuickDraw II and Font 
Manager tool sets. The size of the text is determined by the font 

chosen.) 

The QuickDraw II tool set in the Apple lies Toolbox is respon- 
sible for all graphics appearing on the screen. Drawing lines, cir- 
cles, boxes, arcs, and patterns is easy once you learn how to use 
the over-250 routines provided by QuickDraw II. By using 
QuickDraw, you save development time. It eliminates the necessity 
of writing graphics primitives. The basic code has been written for 
you. Also, sticking to the QuickDraw routines ensures that your 
graphics programs will work on and be compatible with all future 
releases of the Apple IICS. 



Sound 

To make the Apple IIGS more competitive and attractive to the 
marketplace, something had to be done about sound. Sound was 
one thing the Apple II series of computers barely provided. 

For years, Apple II programmers created sound by bit twid- 
dling. The speaker has a memory location— $C030. By peeking this 
location from Applesoft BASIC or by examining this location using 
assembly language, the speaker could be made to tick (see follow- 
ing box). A rapid succession of ticks produced a tone. By varying 
the number of ticks and their duration, a chorus of tones could be 
created. This complicated-yet-simplistic method of producing sound 
got the job done, yet there had to be a better way. 
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To tick the speaker in Applesoft BASIC, the PEEK state- 
ment is used. PEEK returns the byte value of a specific mem- 
ory location, in this case $C030, which is 49200 decimal: 

A = PEEK (49200) 

The actual value of A can be discarded. By repeatedly 
reading memory location 49200, as well as varying the inter- 
val between PEEKs, the speaker can produce a variety of 
tones. Note that PEEK'S counterpart, POKE, has no audible ef- 
fect on memory location 49200. 

The following program shows how the PEEK statement in 
Applesoft BASIC can be used to tick the speaker: 

10 FOR X = 1 TO 10 

20 A = PEEK (49200) 

30 FOR T = 1 TO 10 : NEXT T 

40 A = PEEK (49200) 

B0 NEXT X 

The two PEEK statements in lines 20 and 40 tick the 
speaker. Line 30 contains a delay that produces the pitch of 
the tone: Increase the delay, and the pitch deepens; decrease 
the delay, and a higher pitch is produced. The main FOR- 
NEXT loop between lines 10 and 50 sets the duration of the 
tone. 



The better way turned out to be the Ensoniq 5503 Digital Os- 
cillator Chip (DOC) included with the Apple IIGS. This is the same 
chip that appears in many of Ensoniq 's synthesizers and MIDI 
(Musical Instrument Digital Interface) equipment. 

The DOC contains 32 oscillators. These are paired to form 15 
voices, each capable of producing its own sound (like 15 separate 
instruments in a band). The sixteenth voice is used internally for 
timing purposes. 

Also included with the DOC is 64 K of RAM referred to as 
sound memory, or sound RAM. Into this special area of memory can 
be placed various waveform patterns or even digitized samples of 
analog sounds such as a human voice. 
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The DOC can be programmed on two levels. Low-level pro- 
gramming involves reading and writing to the DOC's sound RAM 
and altering its registers directly. This method is complex, yet it's 

Proven. In fact, the majority of the Apple IlGS sound applications 
roven. In fact; the majonty of tne Apple JIGS souno applications 

available use this technique. The second way to program the DOC 
is using the Apple IlGS Toolbox. This is the preferred way. The ad- 
vantage of Toolbox routines becomes clear when you consider that 
three lines of code are required to play a note using the Toolbox 
and 30 or more lines of code and data statements would be re- 
quired to play the same note using low-level routines. But there is 
a problem: The Toolbox sound routines aren't finished. 

Soon, you'll be able to choose from a variety of sounds and 
tones as easily as opening a window. Apple is fast at work com- 
pleting the sound routines, Unfortunately, they won't be finished 
in time for inclusion in this book. 



The sound lab in the Advanced Technologies section of 

Apple Computer is impressive. The goal of the researchers is 
to create a sound environment for computers that is as ad- 
vanced as the computer's graphics capabilities. While graphics 
have continually progressed, and programming the graphics 
has become easier, sound continues to be an orphan. 

In the lab, they're concentrating on not only making 
sound easier to program, but on how to tailor sound toward 
specific applications. According to one of the researchers, 
"Any computer can go beep.' What about other sounds? How 
can they enhance the performance of a piece of software? 
How can sound help a user better interact with a program?" 

Sadly, all this technological magic is being worked out on 
a Macintosh II, not an Apple IlGS. The researchers want you 
to know, however, that all information discovered will be 
shared with the IlGS development team. You may see interest- 
ing and exciting sound advancements on this computer in the 
near future. 
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The 65816 Processor 

The actual brain of the Apple lies is the 65816 microprocessor. It's 
the latest generation of the 6502 series of processors. This family 
began with the 6502 microprocessor used in the first Apple com- 
puter. Since that time, the chip has been improved upon. It became 
faster and able to address megabytes of memory and handle 16-bit- 
wide operations. 

Figure 2-1. Apple IIgs Motherboard with 65816 Pointed Out 




The 65816 is the brain of the Apple IIgs. 

To maintain compatibility with the older 6502 chips (and the 
software that ran on them), the 65816 can emulate a 6502. In the 
emulation mode, it behaves exactly as a 6502 would, with very few 
exceptions. While emulating its ancestor, the Apple IlGS works on 
eight bits of data at a time and can access only 64K of memory. 

Note that while the 65816 is capable of emulating the 6502, 
older machines using the 6502 cannot run 65816 machine language 
programs. In fact, most of the 65816 machine language instructions 
are not defined for the 6502, Running a 65816 program on one of 
those machines (which would be hard to do in the first place) 
would crash the computer. 
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Figure 2-2. Diagram of 6502 
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The 6502 chip used in older Apple II machines can only handle eight-bit operations. 
Figure 2-3. Diagram of 65816 
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Programming Subtleties 



When programming, it's possible to switch emulation on and 
off, as weU as configure the A, X, and Y registers to either 8 or 16 
bits. In machine language, this is done manually by setting the 
65816 to emulation or native mode and by setting or clearing the 
register configuration bits. If you use the APW assembler, special 
assembler directives must be used to ensure that all following code 
is interpreted properly for the emulation mode. (See the APW man- 
ual for details.) 

When programming in Pascal or C, emulation or native mode 
selection is taken care of automatically, either by default or through 
certain directives, depending on the software used. It's not neces- 
sary to ensure the processor is in one mode or the other when pro- 
gramming in Pascal or C. 

To access the Toolbox, the 65816 must be in its native mode 
and all registers must be configured to 16 bits. 

Apple He Emulation 

One of the smartest things Apple Computer has done is to ensure 
that the software used on older Apple computers will work on new 
machines. Lack of compatibility has killed more than one 
microcomputer. 

Figure 2-4. Apple IlGS Motherboard with Mega II Pointed Out 

I 




The Mega II: An Apple He all on one chip. 
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Programs that ran on the Apple II can run on the Apple II + . 
Apple 11+ programs run on the Apple He and Ik. And the majority 
of those programs (about 90 percent) still run on a brand-new Ap- 
ple IlGS. The reason for this is that the Apple IIGS contains a cus- 
tom chip called the Mega II. The Mega II is an Apple He all on one 
chip. 

Operation of the Mega 11 is transparent as far as programming 
the machine goes. While running older Apple II software, the Mega 
II takes charge and causes the machine to be an Apple He. When 
running Apple IlGS software, the Mega II does handle some opera- 
tions. For the most part, however, its purpose is to emulate an Ap- 
ple He and provide compatibility for older applications. 



The Mega II has an interesting history. Apparently, the 
Mega II took the Apple lies design team by surprise, People 
"upstairs" requested that the Mega II (supposedly designed for 
some other project) be used in the Apple IlGS. Because of this 
addition relatively late in the IlGS design, the Mega II chip 
contains many features made redundant by the VGC video 
chip. 

A slightly less-than-delighted design team did successfully 
incorporate the Mega II into the Apple IlGS, and it does per- 
form its job very well. One question remains: What was the 
original purpose of the Mega II? A one-chip He or He, per- 
haps? Only time will tell. 



Memory Addressing 

The Apple IlGS has an alluring ability to address a tremendous 
amount of memory. This will be particularly attractive to program- 
mers weaned on 64K (or even 128K) computers. Technically, the 
65816 is capable of addressing 16 megabytes. The way the Apple 

IIos lb luneiuly UeMgueiJ, vjiiI^ uicgaUyles of mciiiujj iwi be 

used for RAM, but that is still more than you're ever likely to need. 

The eight megabytes of memory are divided into 128 separate 
banks of 64K each. The full 16 megabytes represents a total of 256 
banks. Several of those banks are dedicated to the computer's 
ROM, possible ROM upgrades, and the Mega 1 1 chip. The memory 
map in Figure 2-5 shows how the memory banks are allocated in 
the Apple IlGS. 
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Programming Subtleties 



Figure 2-5. Memory Banks in the Apple Hgs 
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Each memory address (location) in the computer's RAM is rep- 
resented by a bank number and an offset within that bank. For ex- 
ample, address $000200 indicates memory location $0200 in bank 
$00, the first bank of memory. Memory location $00A8 in bank 
$E1 is expressed as SE100A8. The First byte value represents the 
bank number, the second word value indicates an offset within that 
bank. 

It's assumed that a leading $00 precedes all memory addresses. 
Because $E100A8 is not a true long-word value, the actual address 
is $OOE100A8. However, because the MSB of the high-order word 
is always $00, it's usually left off (or assumed). 

Allocating and controlling all this memory is the job of a very 
special tool set called the Memory Manager. One of the most im- 
portant tool sets in the Toolbox, the Memory Manager is responsi- 
ble for divvying up and setting priorities to blocks of memory. It's 
so well implemented that you need not know the exact location of 
a memory block. The Memory Manager takes care of all that for 
you. Blocks of memory can be moved, deactivated, or purged all 
via a call to the Memory Manager. 

More details about memory and the Memory Manager can be 
found in Chapter 7. 
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Because the Apple IIGS currently comes only with 256K 
on the motherboard, you'll need to upgrade your machine's 
memory (as has been previously recommended). When you 
upgrade, you'll probably purchase a RAM card that allows you 
to use 256K RAM chips. Eight of these chips are equal to 256K 
of memory. The Apple IIGS considers 256K to be four banks. 

As you add memory, the lies automatically assigns that 
memory to banks, beginning with bank $02. (Remember that 
you already have four banks of memory. Banks $00 and $01 
are built-in FPI RAM, and the Mega II RAM and I/O are lo- 
cated in banks $E0 and $E1.) The typical memory card comes 
with at least four blocks which can each hold 256K of mem- 
ory, making it capable of holding up to one megabyte of 
memory — 16 banks of IIGS memory. 

Memory cards with more than four blocks of 256K may 
cause some problems with future releases of the Apple IIGS. 
According to its designers, a memory card should have a max- 
imum of four blocks of 256K. But certain hardware developers 
thought they could put more on a memory card. While the 
memory upgrade cards will still function, and the IIGS will be 
able to make use of the extra memory, some problems may 
result. 

The best way to avoid problems when using a memory 
card with more than four blocks of 256K is to assign the extra 
memory as a ramdisk. This can be done using the Control 
Panel's ramdisk. 

For example, the development systems this book was 
tested on contained RAM cards with 1.75 megabytes of RAM 
on them (six blocks of 256K). With an 800K ramdisk selected 
(the same size as the IIGS disk drive), the rest of the memory 
fit easily into the four-block maximum, and there were no 
problems. 






Operating Environment 

The operating system for the Apple IIGS is ProDOS 16, a custom 
operating system for the IIGS based on Apple's ProDOS 8 (which 
used to be just ProDOS). ProDOS 16 is very similar to ProDOS 8. 
In fact, updating is as easy as copying the ProDOS 16 files onto 
your old ProD05 8 disks or hard drive. 
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ProDOS 16 controls disks and manages the file system. It uses 
the same file structure as ProDOS 8 and will even recognize, load, 
and run ProDOS 8 Files, such as AppleWorks. However, ProDOS 8 
cannot run the ProDOS 16 files. (And ProDOS 16 will not run on 
an Apple lie, lie, or 11+) 

Incidentally, ProDOS 16 serves as a file-management system 
and isn't a true operating system in the sense that UNIX, MS-DOS, 
or OS/2 are operating systems. In fact, in the old days, all pro- 
gramming tasks were taken care of by the Apple's built-in BASIC 
interpreter. A program was run by typing its name at the BASIC 
command prompt, prefixed by a hyphen; 

]-APLWORKS.SYSTEM 

The absve §A§[£ eammat^ wsuld run the AwW.wfe pr^ 

gram, provided an AppleWorks disk was in the disk drive. (Another 
method to run Apple Works was to place the AppleWorks disk into 
the primary disk drive and reboot the computer.) 

The Apple IIGS provides a better way to interact with your 
programs. 

Since late 1987, Apple introduced a Finder program, similar to 
the operating environment of the Macintosh. In fact, if you're fa- 
miliar with the Mac, the IIGS Finder looks like a color version of 
the Mac's. Programs, data files, and file folders (which contain sub- 
directories) all appear as graphics images on the screen. The Finder 
allows files and programs to be manipulated with relative ease as 
compared to the older, slower ProDOS utilities. And, not only can 
ProDOS 16 and native Apple IIGS applications be run using the 
Finder, but because Apple also included a copy of ProDOS 8 on 
the Finder disk, older Apple II applications can be run as well, 

Unlike the Macintosh's Finder, however, the Apple II Finder 
does have some limitations. Most notable among them is that not 
all Apple II applications are based on the graphic DeskTop envi- 
ronment. Older applications — and even some new ones — still use 
the Apple's text screen. Most of the newer applications, including 
examples in this book, will use the graphic environment of the 
DeskTop. 
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How Programs 
Work 



One trait most avid computer 
programmers share is a love of 
solving puzzles. Most great pro- 
grammers are also great puzzle 
solvers. The self-taught com- 
puter wizard can unravel mys- 
teries and evoke programming 
incantations that make a ma- 
chine perform magical feats. 




Chapter 3 

These programmers are not satisfied with just getting the job 
done. They want to make code tighter, faster, more ingenious. This 
chapter is directed to them. 

This chapter explains how programs work on the Apple IlGS. 
Of course, if the subject doesn't make any sense, please read on. 
Whether you're a programming wizard or just an apprentice, this 
chapter contains interesting background information on how the 
lies works, how programs are loaded, what happens when they 
start, and where they go when they die. It's a chapter full of secrets 
revealed and undercover skullduggery — ideal for the potential pro- 
gramming prodigy. 

Anticipation 

Before you can begin serious programming on the Apple IlGS, you 
will need at least one disk drive and a system disk. The program- 
ming tips in this book were tested on one of the original computers 
using system disk version 3.1, as well as one of the later ROM 01 
machines, so it should be applicable to your machine. 

Of course, by the time you read this, ROM version 09 and sys- 
tem disk version 86 might be available. Things change that quickly. 
But don't worry. The information in this book is still good and all 
of it applies. 

When you turn on your Apple IlGS, it looks for the startup slot. 
This is one of the slots on the motherboard into which a disk drive 
should be plugged. A specific startup slot can be specified in the 
Control Panel, or you can set it to scan. When set to scan, the Ap- 
ple HGS will scan all slots for the appropriate startup device. 

When scan is selected, the system begins looking for an I/O 
device starting with slot 7 and continues searching down to slot 1. 
For example, if you have a hard disk drive connected to slot 7, that 
will be the startup device. Otherwise, the scan continues with slot 6 
(the old floppy drive slot), slot 5 (the 3Va-inch drive slot), and so on. 

If you have selected a specific slot from the Control Panel, 
your HGS will look for a startup device in that slot only. This way, 
if you had a disk controller card in slot 6 and you wanted the com- 
puter to startup from that device, it would do so, regardless of 
what was in the other slots or what devices were plugged into the 
IlGS ports (on the back panel). 
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The connectors on the back panel of the computer are 
really considered devices plugged into slots, In fact, if you run 
an old Apple lie diagnostic program, it assumes you have ev- 
ery slot in the computer filled with specific devices, even 
though your IIGS may be totally empty inside, 



Once the computer is turned on, its primary job is to find a 
disk drive. Once the disk drive is found, the computer checks to 
see whether a disk is in that I/O device. If not, or if the disk is of 
alien origin, the following message is displayed along with the Ap- 
ple character bouncing back and forth across the screen: 

Check startup devtcel 

If a disk is found, the computer checks to see whether it's a 
boot disk, specifically, a ProDOS disk. If it's either a ProDOS 8 or 
16 system disk, the system continues to load ProDOS from disk. If 
the disk is just a data disk (meaning there's no operating system 
present) the following is displayed: 

'" UNABLE TO LOAD P'HODOS "■ 

If this or the previous message is displayed, you should insert 
a ProDOS system disk into your disk drive and try again. 

If you do have a bona fide ProDOS disk in the drive, your llGS 
will attempt to load ProDOS into memory. For ProDOS 8, this is a 
very simple operation. For ProDOS 16, things are a little more 
complex. 



The original disk operating system tor me Apple ll com- 
puter was simply called DOS, for Disk Operating System. It 
went through various iterations until its final version, DOS 
3.3, was replaced by ProDOS in early 1983. 

ProDOS was modeled after the SOS operating system Ap- 
ple developed for the late Apple III computer. SOS stood for 
Sophisticated Operating System. 

SOS introduced the hierarchical file system of volumes 
and prefixes now used by ProDOS. In fact, SOS files and 
ProDOS 16 files have identical structures to a certain extent. 
And because the Apple HE Pascal used a file system similar to 
SOS. ProDOS 16 can read Apple III Pascal files as well. 
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Booting ProDOS 8 

Because the Apple IlGS is Apple He compatible (for about 90 per- 
cent of the programs, according to the literature), it can load and 
run a ProDOS 8 program just as if it were a He. Due to this 
compatibility, it's logical to assume that both ProDOS 8 and 
ProDOS 16 are initially loaded from disk in a similar manner. 
The program (actually ROM code) that loads ProDOS into 
memory is called Boot ROM. These instructions are located on the 
disk's controller card. The actual memory location of the Boot ROM 
is in memory bank $00, at location SCOOO plus $100 times the slot 
number. So, if slot 6 contains the disk's controller card, the Boot 
ROM is at memory location SC0O0 plus $100 X 6, or $C600. (All 
memory locations from here on are in bank $00 unless other 

specified.) 

Boot ROM has only one job: to read in the first one or two 
blocks of the disk (or hard disk) into memory. The contents of 
these blocks are copied to memory location $800. With its dying 
breath, the Boot ROM's last job is to perform a JMP instruction to 
the machine language routines (loaded from disk) at the address 

$801. 

The routine loaded from disk is $200 bytes long and occupies 
memory locations $800 through $9FF. If the disk being booted is 
formatted for ProDOS (either version), the information loaded from 
disk is called the ProDOS Boot Loader. This code will read in the 
rest of block 0, as well as the entire contents of block 1 of the disk. 
However, the information on block 1 is used primarily by the Ap- 
ple III computer as a means of booting into the SOS operating 
system. 



A block, the smallest unit of storage on a ProDOS disk, 
consists of 512 bytes of information. A sector, the smallest ac- 
cessible unit of a DOS 3.3 formatted disk, holds only 256 

bytes. 



The Boot Loader's job, like the Boot ROM, is to load more 
information from disk— in this case, the rest of ProDOS. The 
ProDOS Loader searches the disk's volume, or root, directory for the 
file called PRODOS, which contains the ProDOS Relocator. If this 
file cannot be found, the following message is displayed: 

••• UNABLE TO LOAD PRODOS "' 
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It's not unusual to see this when booting data disks. They're 
formatted for use with ProDOS, but aren't meant to be booted. 

If the PRODOS file is found, it's loaded into memory locations 
$20QQ-$5BFF. And. like the Boot ROM, with the Loader's dying 
breath, it jumps to the machine language routines at address $2000 
which make up the ProDOS Kernel Relocator. 

The ProDOS Relocator is the program that prints the ProDOS 
version number and copyright on the screen. It does a number of 
other interesting things: evaluating RAM, determining the type of 
Apple computer you have, and so on. But its biggest job is to copy 
the ProDOS Kernel, the actual operating-system part of ProDOS, to 
high memory. It also sets up the System Global Page. Incidentally, 
when the Relocator is copying the Kernel image to high memory, it 
makes a grating sound on the computer's speaker. 

Once the relocated Kernel is running, ProDOS 8 scans the vol- 
ume directory of the disk for a system file with a .SYSTEM suffix. 
If a .SYSTEM file is found— BASIC.SYSTEM, for example— it's 
loaded into memory at location $2000, and then a JMP instruction 
is performed to that address. 

If the SYSTEM program is in fact BASIC.SYSTEM, the BASIC 
interpreter looks for a BASIC program named STARTUP in the vol- 
ume directory. If found, that program is loaded into memory, and 
its instructions are executed. 

This may seem like a very complex way of loading in some- 
thing as simple as a BASIC program. Yet, nearly all microcomput- 
ers operate this way: First, a small bit of the disk is read, then a 
larger piece, and then, finally, the operating system is loaded into 
memory. It would probably be much more efficient to directly load 
the entire operating system when a computer starts, but not as flex- 
ible. Imagine all your data disks needing a 30-block boot sector 
simply to display the message, ***UNABLE TO LOAD PRODOS***. 



Actually, a better justification for loading ProDOS in 
pieces is to allow the system to run more than one operating 
system. For example, using this method, an alien operating 
system could have its own Boot Loader on the first two sectors 
of a disk. This custom Boot Loader could then look for a spe- 
cial Loader file on disk — something other than PRODOS. The 
new Loader file could then load itself into memory and the 
Apple IIGS would run a new operating system, such as the old 
Apple Pascal. 
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Youil really appreciate the speed with which ProDOS 8 loads, 
especially after you have encountered the apparently sluggish 
ProDOS 16. 

Booting ProDOS 16 

As they're started, ProDOS 8 and ProDOS 16 are remarkably simi- 
lar They have to be similar, so they are compatible and use the 
same disk structure. But bear in mind that although the Apple IIGS 
can boot ProDOS 8 disks and run ProDOS 8 applications, older 
Apple Us cannot run ProDOS 16 nor can they run Apple lies 
applications. 



Actually, as far as the computer is concerned, it doesn't 
matter whether the operating system is on disk or not. All it's 
looking for are the first two sectors, which it copies from disk 
into memory beginning at location $800. It then executes the 
instructions beginning at location $801, whether they mean 
something or not. 



As with ProDOS 8, the first thing the Boot ROM does is load 
disk blocks and 1 into memory location $800 in bank $00. The 
next step is also similar. In starting a ProDOS 16 disk, the program 
at $800 (the boot code) looks for a file named PRODOS in the vol- 
ume directory— the same name as the ProDOS 8 Relocator. If the 
PRODOS file is not found, the '"UNABLE TO LOAD PRODOS"' 

message appears. , , 

These similarities are not remarkable coincidences. t his is De- 
cause a disk formatted for ProDOS 16 will contain exactly the same 
boot code on blocks and 1 as does a ProDOS 8 disk. 

Once the jump is made to memory location $2000 (the 
PRODOS program), the two operating systems behave quite differ- 
ently. The PRODOS program under ProDOS 8 is the Relocator and 
Kernel— the actual operating system. Under ProDOS 16, the 
PRODOS file loaded at memory location $2000 is just another link 
in a long chain of commands. 



If yOU try to bOOt ProDQ§ 16 °n an Apple II other than a 
IIGS, the following is displayed: 

PRODOS 16 REQUIRES APPLE IIGS HARDWARE 
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The primary duty of the PRODOS file is to pass execution to 
the Apple 11GS System Loader. But before it does that, it sets up the 
ProDOS 16 quit code by transferring that part of itself to memory 
location $DO00 in bank-switched memory. This code, referred to as 
PQUIT, stays in memory permanently and is used when a program 
quits. (The actual memory location is one of those pieces of infor- 
mation that you don't really need to know. There is no practical 
purpose for knowing that the code is loaded into the $D000 loca- 
tion, except to impress your friends.) 

The Apple IlGS System Loader file is named PI 6. It's found in 
the SYSTEM subdirectory on the boot disk. The System Loader 
works closely with ProDOS as well as the Memory Manager to al- 
locate, relocate, load, and save information between the disk drives 
and memory. As the System Loader (PI 6) is started, it displays a 
name and version number on the screen, just as ProDOS 8 does. 
See Figure 3-1. 

Figure 3-1. System Loader Display 

APPLE II 

PRODOS 16 V1.3 39-JUN-87 

LOADER VI. 3 

COPYRIGHT APPLE COMPUTER, INC., 1983-87 

ALL RIGHTS RESERVED. 

The ProDOS version number appears after booting a system 
disk. VI. 3 is the version and release number of ProDOS 16 (PI 6), 
as well as the System Loader (PRODOS) file. In the above ex- 
ample, both numbers are the same, though that may not always be 
the case. 

Once ProDOS 16 is in memory, the PRODOS Loader (still in 
memory at $2000) continues its job. It looks in the 
SYSTEM/SYSTEM. SETUP subdirectory. All files in this directory 
are executed, starting with the file named TOOL.SETUP. 

TOOL.SETUP patches or modifies any of the ROM tool sets 
(ID numbers $01-$0D). This file must be in the SYSTEM/ 
SYSTEM.SETUP directory, and it is executed ahead of any other 
files in the subdirectory. 

The SYSTEM.SETUP director}' contains any file or program 
that needs to be loaded or initialized when the system is started. 
Primarily, two types of files can be included in SYSTEM.SETUP, 
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along with TOOL.SETUP: Permanent Initialization files and Tem- 
porary Initialization files. 

Permanent Initialization files. Permanent Initialization files 
have a file type of $B6. They're referred to as STR (STaRtup) files. 
These files are loaded and executed but not shut down like stand- 
ard applications. They're actually more like subroutines because 
they're always in memory and end with an RTL instruction rather 
than calling the ProDOS Quit command. Permanent Initialization 
files must also be loaded into nonspecial memory and cannot allo- 
cate any stack or direct-page space. 

An example of a Permanent Initialization file is the 
TOOL.SETUP program that patches the ROM-based tool sets. 
TOOL.SETUP contains adjustments and modifications to the ROM 
tool sets. It's actually an extension of the ROM code. When Apple 
learns of new bugs in the ROM tool sets, they release a new 
TOOL.SETUP file rather than new ROM chips. TOOL.SETUP must 
always be in memory, therefore it's a Permanent Initialization file 
and not a Temporary Initialization file. 

Temporary Initialization files. Temporary Initialization files 
have a file type of $B7. They're referred to as TSF (Temporary 
Startup File) files. These files are similar to Permanent Initialization 
files, except they are shut down when completed, and their mem- 
ory space is released. But, like Permanent Initialization files, they 
also end with an RTL instruction rather than calling the Quit 
function. 

An example of a Temporary Initialization file is the 
BEEP.SETUP program listed later in this book. BEEP.SETUP re- 
places the normal system beep sound with a more pleasant noise. 
Once BEEP.SETUP completes its task, it's removed from memory 
(see Chapter 1 2 for more information on BEEP.SETUP). 

After the SYSTEM.SETUP directory is scoured, and the STR 
and TSF programs are run, ProDOS looks in the directory SYSTEM/ 
DESK.ACCS to load any desk accessories found there. Classic desk 
accessories (CDAs), with a file type of $B8, are placed into memory 
and can be accessed via the Control Panel. New desk accessories, 
with a file type of $B9, can only be used by DeskTop applications. 
All desk accessories in the SYSTEM/DESK.ACCS directory are 
loaded at this time. 
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You don't need to keep all your desk accessories in the 
SYSTEM/DESK.ACCS subdirectory — only those you want to 
load. Other desk accessories can be kept in a backup directory 
and then transferred to SYSTEM/DESK.ACCS for use when 
the system is rebooted. 



After the desk accessories are loaded, ProDOS looks for a file 
named START in the SYSTEM directory. The file could be an ap- 
plications file, or it could be the Finder or Launcher (discussed 
later). If a START file isn't found, ProDOS looks in the volume di- 
rectory for a file with a suffix of either .SYS 16 or .SYSTEM. The 
.SYS16 suffix indicates a ProDOS 16 file, and that program is 
loaded and executed. The .SYSTEM suffix is for a ProDOS 8 
program. 

If the .SYS 16 program is found first, ProDOS calls its own quit 
code with the name of the .SYS16 file and executes it. If a .SYS- 
TEM (ProDOS .8) file is found first, ProDOS calls a modified 
ProDOS 8 Quit call and executes the .SYSTEM file. However, in 
order to do this, the ProDOS 8 operating system file, P8 must be 
the SYSTEM directory. 

If a SYSTEM/START file— or a SYSTEM or .SYS16 file in the 
volume directory — does not exist, a fatal error occurs. 

All this is done simply to boot the ProDOS 16 disk, so it's easy 
to see how ProDOS 16 can be accused of booting slowly when 
compared with ProDOS 8. However, given the power of this op- 
erating system and all the things it enables a programmer to do, it 
is well worth the extra wait. 

ProDOS 16 Disk Contents 

There are so many files on the ProDOS 16 boot disk that, even in 
the minimum configuration, all of them wouldn't fit on one of the 
old-style 140K disks. Most of these files and their duties were dis- 
cussed in the previous section, but for review (and as a handy ref- 
erence), they are touched on briefly here. The following programs 
(in alphabetic order) are on a sample system disk named /A/. Re- 
member that throughout this section the volume name /A/ is used 
only for reference. Your system disk may have a different name. 
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/A/BASICSYSTEM The ProDOS 8 version of the BASIC interpreter. It 
contains the disk extensions to Applesoft BASIC in ROM. 

/A/PRODOS The System Loader that is responsible for setting up the 
operating system. Toolbox, desk accessories, and generally getting the 
Apple lies running. Remember that both ProDOS 8 and 16 use the 
name PRODOS for their System Loader. One way to tell the differ- 
ence is by looking at the files size. ProDOS 8 is approximately 32 
blocks in size, whereas ProDOS 16 is significantly larger at approxi- 
mately 42 blocks. The sizes may vary depending on the release ver- 
sion, but ProDOS 16 will always be larger. 

/A/SYSTEM/ The directory containing important files and folders (other 
directories). 

/A/SYSTEM/DESK.ACCS Contains new and classic desk accessories to 
be loaded when ProDOS 16 boots. Other desk accessories can be in- 
cluded on your boot disk, but they will be loaded only if they are in 
this directory, 

/A/SYSTEM/LIBS A directory holding system libraries. It appeared on 
the original System Disk, but not on the current (3.1) version. Apple 
may include it on future versions if an application needs library files. 

/A/SYSTEM/P8 The ProDOS 8 operating system. If this file is renamed 
PRODOS and copied to the volume directory, the disk will boot as a 

ProDOS 8 disk. 

/A/SYSTEM/P16 The ProDOS 16 operating system and Apple lies Sys- 
tem Loader. 

/A/SYSTEM/START A program to be run after ProDOS has finished 
loading (the startup program). It may be an actual application or a 
loader file to launch an application. 

/A/SYSTEM/SYSTEM.SETUP A directory containing initialization files 
to be run at boot time. 

/A/SYSTEM/SYSTEM.SETUP/TOOL. SETUP A required file used to 
patch tool sets in ROM. 

/A/SYSTEM/TOOLS A directory containing all the disk-based tools for 
the Toolbox. The tool sets appear with the name TOOL followed by 
the three-digit decimal number of the tool set. So the Window Man- 
ager, tool set ID# $0E, appears in this directory as TOOL014. 

The above are all the files of a typical ProDOS 16 system disk. 
Of course, more files exist depending on the application and version 
of the system disk. Besides DESK.ACCS and SYSTEM.SETUP in 
the SYSTEM directory, the following folders might also be found: 

/A/SYSTEM /DRIVERS A directory containing control files for printers, 
AppleTalk. modems, and a variety of devices. 
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/A/SYSTEM/FONTS A directory containing a variety of fonts to be 
taken advantage of by programs that use them. The files are named 
after the font they describe, followed by a dot and the point size of 
the font. So, COURIER.10 is a ten-point Courier font, and TIMES.12 
is a 12- point Times Roman font. 

Two other files you might find on your system disk are these: 

/A/SYSTEM/FINDER A program, run by the /A/SYSTEM/START pro- 
gram, that contains a DeskTop environment similar to the one found 

/A/SYSTEM/LAUNCHER A simple program launcher, run by the 

/A/SYSTEM /START program. This program was around when the 
original Apple lies arrived and the Finder was not yet completed. 

The Finder uses a number of other files on disk, most notably 

icon files containing the graphic images it uses as icons. The two 
icon files used by the Finder are DIALOG. ICONS in the volume di- 
rectory and FINDER. ICONS in the directory /A/ICONS. (It's per- 
missible to move the DIALOG. ICONS file into the ICONS 
subdirectory to keep your volume directory clean, by the way.) 

If you're writing applications for distribution, you'll have to 
find a way to get the following files and programs on your ProDOS 
16 disk: 

/A/PRODOS 
/A/SYSTEM 
/A/SYSTEM/P16 
/A/SYSTEM/SYSTEM.SETUP 

/A/SYSTEM/SYSTEM.SETUP/TOOL.SETUP 

These files are required by ProDOS 16 in order to boot suc- 
cessfully. However, the startup application will probably require 
tool sets and other support files. 

For example, DeskTop programs may need /A/SYSTEM/ 
FONTS/ (and the fonts) or /A/SYSTEM/START or the .SYS 16 file 
in the volume director)'. BASIC programs will need BASIC.SYSTEM 
and P8. And, if your program uses a disk-based tool set, you'll 
need to include it in the /A/SYSTEM/TOOLS directory. 
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If you plan to write and distribute your applications on a 
ProDOS 16 disk, you should know that your system disk and 
its contents contain software copyrighted by Apple. Only very 
wealthy companies can afford to pay the fees required to dis- 
tribute ProDOS with their programs. For you, as a software 
wizard, it's best to put your applications on a data disk and 
then provide instructions for copying your software to a 
ProDOS disk or to have the user copy ProDOS and the Finder 
to your disk. 

Contact Apple Computer for more information on 
licensing. 



Launching Applications 

Launching a program on the Apple lies is different from running 
programs on older Apples. The Apple lies offers a very diverse 
environment and, as usual, there are always a few more things go- 
ing on than meets the eye. Of course, programmers will love to 
take advantage of the new features of ProDOS 16. 

Because this book is about the Apple lies, ProDOS 8 is be- 
yond its scope. There are many worthy texts already available on 
the subject to which the reader is referred. The concentration here 
will be on launching (or running) applications under ProDOS 16. 

The first and most bizarre feature of ProDOS 16 is that pro- 
grams start with a call to the ProDOS Quit function. A program 
starts by quitting. 

To launch a ProDOS 16 application, the program can be one of 

three types: 

• The program named START in the SYSTEM directory 

• Any program with an SI 6 ($B3) file type 

• Any program with a SYS ($FF) file type 

The SYS file type is a ProDOS 8 application. Even so, the 
ProDOS 16 Loader will recognize this and, as part of the applica- 
tion's startup, ProDOS 8 will be loaded and executed, allowing you 
to run your ProDOS 8 program. 

Programs can also be launched via the Finder or the Launcher. 
Whichever method is used, the program is loaded into memory and 
control is transferred to that program. 
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But there's considerably more to the story than that. If you 
have purchased this book and have read this far, you're probably 
interested in knowing the real information on program launching. 

Launching. Your programs are actually loaded via the ProDOS 
16 Quit call. When one application quits and performs the obliga- 
tory call to ProDOS notifying the operating system that it is fin- 
ished, the program has the option of immediately running another 
program. 

If a second program is not specified, the ProDOS 16 Quit call 
allows any previously launched programs to be rerun, either by re- 
loading them from disk or restarting them from memory. 

When the ProDOS 16 Quit function is called, the program 
making the call is basically finished. It can, however, tell ProDOS 
the following: 

• Which program to run next 

• Whether it can be used again after the next program quits 

If the program doesn't specify the next program, ProDOS 
checks to see whether it can return to any other programs previ- 
ously run, and if not, it executes the special quit code, PQUIT. 

The ProDOS 16 Quit Function 

Programming for ProDOS 16 is different than programming for the 
Toolbox, yet very similar to ProDOS 8. More information on using 
ProDOS is presented in Chapter 14. The ProDOS 16 Quit function 
is number $29. It has two parameters: 

• The pathname of an optional program to run 

• The quit-parameter word 

To call ProDOS on the Apple llGS, a long jump is made to the 
ProDOS vector in memory bank $E1, offset $A8: 

Jsl IE1Q0A8 ;Call the ProDOS vector 

The JSL instruction is followed by two values. The first value 
is the function number, and the second is the long address of the 
parameter list: 

Value Size 

Function number Word 
Parameter address Long word 
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The function number is a word-sized value, and the parameter 
address is the memory location of a list of parameters required by 
the call. A sample Quit call in machine language would be 

jsl ♦E100A8 ;ProD08 vector 

d C 12'428' .Function number *29, Quit 

do 14'Params' ^Address of Parameters 

Or, if using macros (discussed in Chapter 4): 
_QUIT Parama ;eee above 

The information at the address indicated by the label Params 
contains the address of a pathname of a program to run, plus the 
quit parameter word. For example: 

Parame Anop ;Memory Address of parameters 

do I4"0' ;A long word of zero, no pathname 

do lg'O' ;qult parameter word of zero 

This example would be used if a program were just quitting 
and not running another program. Using a long word of for the 
pathname tells ProDOS to quit without running another program. 

If the program were quitting and running another program, the 
following parameters might be used: 

Params Anop 
dc 
do 



14'Prog' ;The addrees of Prog's pathname 
12'0' ;o.ult parameter word of zero 



L 



The label Prog, in this case, is the address of the pathname of 
a program to run next: 

p rog ,] C ii-H' ;muet start with a count byte 

dc '/GAMES/MONSTER' pathname to run 

In ProDOS, pathnames are always preceded by a count byte 
denoting the length of the path, which follows immediately. If a 
program were to quit with the above Params, the program MON- 
STER on the GAMES volume would be run. 

This is how one program can run another and how the Finder, 
Launcher, APW shell, TML Pflscaf environment, and a plethora of 
other shells and operating systems will load and execute programs. 
They'll all do it via the ProDOS 16 Quit call. 
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The Quit-Parameter Word 

If you don't want to run another program, or if you want to run 
another program and then have control come back to the original 
program, that is where you need the quit-parameter word. 

The quit-parameter word is part of the ProDOS 16 Quit func- 
tion's parameter list (see above). Out of the 16 bits of this word, 
only two are used. The rest are labeled forbidden by Apple: 

Figure 3-2. The Quit-Parameter Word 

Status: Used Reserved — set to 



Quit: 

Bit: 15 14 



13 12 11 10 9 8 7 6 5 4 3 2 1 



Bit 15, Bit 15 of the quit parameter controls the quitting pro- 
gram's User ID (discussed later in this book) and whether or not 
the program will restart after a second program quits. (Each pro- 
gram has its own, unique ID number.) Bit 14 determines if the pro- 
gram quitting can be restarted from memory or should be reloaded 
from disk. 

To stop one program, start another, and then return to the 
original program requires some fancy footwork. To assist in this 
ballet, ProDOS maintains something called a Quit Return Stack. As 
each program quits, it has the option of placing its User ID 
(uniquely identifying that program) onto the Quit Return Stack. 

Likewise, when a program quits, ProDOS checks the Quit Re- 
turn Stack for a User ID. If found, the program identified by the 
User 3D is run again. It's like magic. 

If Bit 15 of the quit parameter is set to 1, the quitting pro- 
gram's ID number is pushed to the ProDOS 16 Quit Return Stack. 
This means that, once a second program is done, control will return 
to the original program. 

This is how programs like the Finder and Launcher work. 
When you select a program to run, the Finder sets bit 15 of the 
quit-parameter word and calls the ProDOS Quit function to run 
that program. Because this bit is set, the Finder or Launcher's User 
ID is saved on the ProDOS 16 Quit Return Stack. When the pro- 
gram you've selected is finished, ProDOS checks the Quit Return 
Stack, removes previous program's ID number, and returns to that 
program. 
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If Bit 15 were not set when the first program quits, then what- 
ever program belongs to the User ID pulled from the Quit Return 
Stack is run. If the Quit Return Stack is empty, control returns to 
the PQU1T code established by PRODOS when the machine was 
booted. 

Bit 14. Bit 14 of the quit -parameter word determines whether 
or not the program making the Quit call can be restarted from 
memory or should be reloaded from disk. If bit 14 is set to 1, the 
program can be restarted from where it sits in memory. If it is reset 
to 0, the program must be reloaded into memory by the System 
Loader. (This is all done by ProDOS. All you do is set or reset the 
bit.) 

So, launching a program on the Apple IIGS starts with a Quit 
call. Quitting programs can specify the name of another program to 
run, as well as determine whether control returns to the original 
program after the second is run. 

Programs may crash when run through a debugger because of 
the way the ProDOS 16 Quit function works in conjunction with 
the Quit Return Stack: When your program makes a ProDOS Quit 
call, the operating system becomes confused because the debug 
program is still running. This causes the system to crash. When 
using the trace mode in DEBUG, place a breakpoint before your 
code to make the ProDOS 16 Quit function call. 

Computer States at Runtime 

When ProDOS passes control to a program via the Quit call, the 
System Loader determines whether the new program is relocatable, 
or must reside at a specific location in memory. When this deter- 
mination is done, the program is allocated its own space, given its 
own zero page, and enough memory to operate. A number of other 
things can happen, depending on the program and how it was 
loaded. 

Only file types $B3-$BE can be loaded by the System Loader, 
and only file types $B3 and $B5 can be run as programs (and speci- 
fied by a Quit call). If a file of an unusual type is specified, the Sys- 
tem Loader reports error $5C, Not an executable file. 
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Type 


Hex 


Dec 


S16 


B3 


179 


RTL 


B4 


180 


EXE 


B5 


181 


STR 


B6 


182 


TSF 


B7 


183 


NDA 


B8 


184 


CDA 


B9 


185 


TOL 


BA 


186 


DRV 


BB 


187 




BC 


188 




BD 


189 




BE 


190 



Table 3-1. ProDOS 16 Load File Types 

Description 

ProDOS 16 system application file 
APW runtime library file 
ProDOS 16 shell application file 
ProDOS 16 Permanent Initialization File 
ProDOS 16 Temporary Initialization File 
New desk accessory 
Classic desk accessory 
ProDOS 16 tool set file 
ProDOS 16 driver file 
System use 
System use 
System use 

Unlike older ProDOS 8 applications, there is no way to be cer- 
tain exactly where a program running under ProDOS 16 will be 
put in memory. (ProDOS 8 programs were always loaded at mem- 
ory location $2000 in bank $00.) However, there are a few guaran- 
tees made by Apple regarding the state of the system when your 
program takes control. 

As with the Boot ROM, once the Loader places your program 
into memory, control of the machine passes to the first instruction 
of your program. Because the Apple IlGS is a single-tasking com- 
puter, meaning it's capable of doing only one thing at a time, your 
program has complete control when it starts. The computer states 
listed in Table 3-2 will be set at the time your application is 
launched. 

Table 3-2. The 65816 Registers Set at Launch 



Register 


Type 


Value 


A 


Accumulator 


The application's User ID 


X 


Index 


$0000 


Y 


Index 


$0000 


S 


Stack pointer 


The top of stack space 


D 


Direct page 


The bottom of stack space 


P 


Processor status 


All zero, native 65816 mode 


PBR 


Program bank 


Determined by the Loader 


DBR 


Data bank 


Determined by the Loader 


PC 


Program counter 


Determined by the Loader 
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The addresses pointed to by the S and D registers are in bank 
$00. (The stack and direct page must always be in bank $00.) For 
example, the S register might point to $1BFF, and the D register 
might point to $1800, defining the stack and direct-page space to 
that $400 byte block. Note, however, that tool sets must request 
their own direct-page space from the Memory Manager (see the 
next chapter). 

The values of the program and data bank registers, as well as 
the program counter will be determined by the Loader and what 
your application requires. There is no guarantee that the program- 
bank and data-bank registers will be pointing to the same bank of 
memory. 

Other aspects of the system are set as follows: 

- The standard input and output devices used by the Text tool set 
are both set to the Pascal 80-column video screen. These can be 
changed by using the Text tool set commands to specify new in- 
put or output devices. However, at startup, both are set to the 
Pascal 8Q-eolumn device, also loosely referred to as the screen. 

• Memory shadowing is set on for the language card, I/O spaces, 
and text pages, and is set off for the graphics pages. Unless you 
are truly an expert, it is not recommended that you alter memory 
shadowing. 
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About the 
Toolbox 

The Toolbox is crucial to pro- 
gramming the Apple IIGS. All 
the routines necessary for pro- 
gramming the Apple IIGS are 
kept in the Toolbox, But the 
Toolbox is more than a simple 
set of programming routines: 
It's the secret to writing pro- 
grams and developing DeskTop 




Chapter 4 

applications for the Apple IIGS. Know the Toolbox, and you can 
master the machine. 

This chapter introduces the Apple IIGS Toolbox. The Toolbox 
contains about 1000 unique routines (called functions) that take 
much of the effort out of programming the Apple IIGS, Though the 
name Toolbox is accurate when it describes these routines and func- 
tions as tools, it might be more fitting to refer to the Toolbox as a 
treasure chest of programming features. 

This chapter won't detail the operation of the Toolbox, but it 
does show how to use the Toolbox to your best advantage. For de- 
tailed information about the Toolbox, including a complete list of 
the Toolbox function numbers and parameters, refer to a compre- 
hensive reference, such as that found in COMPUTED Mastering the 
Apple IIGS Toolbox. 

Toolbox Briefing 

The Toolbox contains routines found in the computer's ROM as 
well as some routines that must be loaded from disk into RAM 
(called disk-based tools). The nearly 1000 unique functions in the 
Toolbox are grouped into 28 different categories called too! sets. For 
example, all of the functions related to the manipulation of win- 
dows are found in the Window Manager tool set, the pull-down 
menu functions are in the Menu Manager tool set, and so on. (See 
Table 4-1 for a complete listing.) 

A tool set can contain as many as 255 different functions. At 
present, the QuickDraw II toot set, the largest by far, contains 206 
unique routines. 

Each tool set function is given a unique identification number. 
The number shows which tool set the function belongs to and 
gives the individual function number within that tool set. Together, 
these two numbers create a two byte (16-bit, or word-sized) num- 
ber identifying the function. One byte gives the too! set; the other, 
the function number: 

function number (1 byte) tool set number (1 byte) 

The byte representing the function number comes first, fol- 
lowed by the tool set. It's backwards, but it's consistent. All of the 
functions in the Toolbox are identified this way. For example, the 
Miscellaneous tool set is tool set number $03. A function within 
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that tool set, SysBeep, is function number $2C. SysBeep is referred 




to as function $2C03 in the Toolbox: 




function number ($2C), tool set number ($03) 




SysBeep = $2C03 




The tool set ID is the low-byte value of $03, and the function 




ID is the high-byte value of $2C. Any other function in the Miscel- 




laneous toot set will also end with the low-byte value of $03, but it 




will have a different high-byte value. 




Table 4-1 contains a complete list of tool sets, their names, and 




ID numbers. Note which ones are found in ROM and which ones 




are located on disk. 




Table 4-1. Tool Set Chart 




ID Name Where Comments 




$01 Tool Locator ROM 




$02 Memory Manager ROM 




$03 Miscellaneous tool set ROM 




$04 QuickDraw 11 ROM $300 bytes direct-page space 




$05 Desk Manager ROM 




$06 Event Manager ROM $100 bytes direct-page space 




$07 Scheduler ROM 




$08 Sound Manager ROM $100 bytes direct-page space 




$09 Apple DeskTop Bus ROM 




$0A SANE ROM $100 bytes direct-page space 




$08 Integer Math ROM 




$0C Text tool set ROM 




$0D RAM Disk ROM Internal use only 




$0E Window Manager Disk Uses Event Manager's direct page 




$0F Menu Manager Disk $100 bytes direct-page space 




$10 Control Manager Disk $100 bytes direct-page space 




$11 System Loader Disk 




$12 QuickDraw II Auxiliary Disk Uses QuickDraw's direct pages 




$13 Print Manager Disk $200 bytes direct-page space 




$14 Line Edit Diet $1fin hytnc Hi ?•«»/-». page cparo 




$15 Dialog Manager Disk Uses Control Manager's direct page 




$16 Scrap Manager Disk 




$17 Standard File Disk $100 bytes direct-page space 




$18 Disk Utilities Disk (No information) 




$19 Note Synthesizer Disk (No information) 




$1A Note Sequencer Disk (No information) 




$1B Font Manager Disk $100 bytes direct-page space 




$1C List Manager Disk 




' 
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The tool set ID is the identification number used to reference 
the tool set during calls to functions. For the sake of convenience, 
and to be consistent with Apple's documentation, hexadecimal 
{base- 16) notation is used. This also makes it easier to spot the tool 
set number when looking at only a two-byte Toolbox function 
value. 

The names listed in the second column of Table 4-1 are the of- 
ficial tool set names. The purposes of most tool sets may be easily 
discerned from their names. The Miscellaneous tool set, number 
$03, contains a hodgepodge of important functions that don't fit 
comfortably under the rubric of any of the other tool sets. 

The third column in Table 4-1 indicates whether a tool set is 
located in ROM (built into the IlGS) or whether it is loaded into 
RAM from disk. 

Additional information is listed under Comments, such as how 
many direct pages are required by the tool set. The tool sets often 
need a certain amount of direct-page memory. Its use is similar to 
BASIC'S use of zero page: as a scratch pad for temporary storage of 
data and pointers. The amount needed depends on the tool set, 
and its use is discussed in greater detail later in this chapter. 

Opening the Toolbox 

Before the Toolbox can be accessed, the microprocessor must be 
placed into native mode. That is, the computer must be running 
with Apple He (Mega II) emulation turned off. Additionally, all reg- 
isters in the 65816 microprocessor must be set to 16-bit widths. 
The following code does this in machine language: 

olo .clear the carry bit 

ice ;and the emulation bit 

rep »I30 :us6 16-bit memory and registers 

Depending on where and how an application has been 
launched, the code above may not be necessary. If the APW or 
ORCA/M assembler is used, there's no need to establish the size of 
the registers and turn off emulation. However, with other assem- 
blers and especially for BASIC programs using the Toolbox with 
machine language subroutines, you must perform the above opera- 
tion. The Toolbox cannot be accessed ivhen the 65816 
microprocessor is in emulation mode. 
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With high -level -language compilers you don't need to worry 
about turning off emulation. AH ProDOS 16 program launchers 
automatically set the 65816 into native (non-emulation) mode 
before your application starts. 

Calling the Toolbox 

To call the Toolbox using machine language, place the function ID 
(tool set number and function number) in the X register. Push onto 
the stack any parameters passed to the function. Finally, make a 
long jump to the subroutine (JSL) at address $E 10000, the Toolbox 
dispatcher. Any parameters returned from the function should be 
pulled from the stack after returning from the function. 

The first Toolbox commandment: Thou shalt not access a 
Toolbox function unless its tool set has been started up. Every 
function in the Toolbox is part of a specific tool set. And before 
that function can be used, its tool set must be started. 

Each tool set has a special function to do this, called the 
Startup function. This function is always function number $02. So, 
before you can use any function in the Miscellaneous tool set you 
must call the MTStartUp function, ID number $0203 ($02 for the 
Startup function and $03 for the Miscellaneous tool set). Once 
StartUp is called, other routines in the tool set can be accessed. 

The specifics of calling the Toolbox, along with step-by-step 
analysis, is provided in COMPUTERS Mastering the Apple UGS Tool- 
box. Refer to that text if these concepts are new to you. 

To perform the MTStartUp function in machine language, the 
X register is loaded with the 16-bit function ID number, $0203 and 
then a JSL instruction is made to memory location $E10000. (JSL is 
Jump to Subroutine Long, and memory address $E 10000 is the 
memory location of the Toolbox.) This is the door through which 
you get to the Toolbox. 

So in order to start this tool set, a machine language program 
would use the following code: 



lax 



*»0803 

tElOOOO 



;MTStartUp 

;8t&rt the Miscellaneous tool Bet 



The short form of this call is 



-MTStartUp 



;Start the Miscellaneous tool eet 
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This is an APW assembler macro call defined in the 
M16.M1SCTOOL macro file (macros and macro files are discussed 
in the nest chapter). Throughout the remainder of this book, both 
the long and short (macro) forms of making Toolbox calls in the as- 
sembler will be used. 

In C, calling the StartUp function is as easy as typing the func- 
tion name. For example, to start up the Miscellaneous tool set, the 
following is used: 
MTStartUpf ); 

And it's done. The information needed by the compiler to per- 
form the Toolbox call is contained in an include file. Just use the 
Toolbox function name in your source code, and the function is 
called automatically. Remember to place the following at the top of 
your C source code listing: 
'Include <mlBCtool.b> 

With Pascal, making a Toolbox call is just as easy. Using TML 
Pascal, the Miscellaneous too! set is started as follows: 

MTStartUp; 

As with C this is simply a statement in your Pascal source 
code. The information is built into the TML Pascal unit file called 
MISCTOOLS.USYM. In the USES portion of your Pascal program, 
you would include this file in the following manner: 

USES MlflcTools; 

Once the tool set has been started up, an application can use 
its features. For example, the SysBeep function, which beeps the 
speaker, is function number $2C03 of the Miscellaneous tool set. 
To call the system beep procedure in machine language, use the 
following: 

Idx 

JBl 

or, if using macros: 
_Sy B Beep ;call SysBeep 



M3C03 

IE10000 



;ttie SysBeep function ID 
;c&ll the Toolboi 
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Remember, the StartUp function has already been called. For 
C, the source would be 

>; 



and in Pascal, simply 



As mentioned previously, in Pascal each Toolbox function call 
contains its definition in a support file. These files can be included, 
used, or copied into your source file, depending on which language 
your program speaks. For example, with the APW assembler, the 
MCOPY command is used to copy macro definitions from external 
macro libraries into your program. In the C language, the #include 
directive causes the compiler to include a header file defining the 
Toolbox calls, as if it were an extension of your source code. Simi- 
larly, TML Pa$ca! incorporates unit symbol files which are brought 
into the compilation step with the USES statement. 

These techniques of including, using, or copying are all cov- 
ered in the next chapter. 

Tool Set Interdependencies 

Many tool sets in the Toolbox call upon other tool sets to perform 
a special operation. This collaboration requires that interdependent 
tool sets — those that rely upon others — must be active and available. 

While your program may only deal directly with the Menu 
Manager, the process of drawing menus relies upon the graphics 
wizardry of QuickDraw II. So your application must start up both 
the Menu Manager and QuickDraw II. To further complicate mat- 
ters, the order in which the tool sets are started is equally 
important. 

Fortunately, the following table presents a list of the interde- 
pendent tool sets, the tool sets they need, and the order in which 
they should be started: 



ID Tool Set 


Tool Sets Required (by Tool Set ID) 


$01 Tool Locator 


None 


$02 Memory Manager 


$01 


$09 DeskTop Bus 


$01 


JOB Integer Math 


$01 


$0C Text tool set 


$01 


$0A SANE 


$01. $02 


$16 Scrap Manager 


$01, $02 



ID 


Tool Set 
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Tool Sets Required (by Tool Set ID) 




$03 


Miscellaneous too! set 


$01, $02, $0B 




$04 


QuickDraw 11 


$01-$03 




$07 


Scheduler 


$01-$03 




$08 


Sound Manager 


$01 -$03 




$19 


Note Synthesizer 


$01, $02, $08 




$11 


System Loader 


$01 -$03 




$12 


QuickDraw Auxiliary 


$01-$04 




$06 


Event Manager 


$01-$05, $09 




$0E 


Window Manager 


$01-$06, $10, $0F 




$14 


Line Edit 


$01-$04, $06, $16 




$10 


Control Manager 


$01-$04, $06, $0E, $0F 




$0F 


Menu Manager 


$01-$04, $06, $0E, $10 




$1C 


List Manager 


S01-S04. $06. $0E. $10, $0F 




$15 


Dialog Manager 


$01 -$04, $06, $0E, $10, $0F, $14 




$05 


Desk Manager 


$01-$04, $06, $0E, $10. $0F, $14, $15, 


$16 


$17 


Standard File 


$01-$04, $06, $0E, $10, $0F. $14. $15 
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Font Manager 


$01-$04, $0B, $0E, $10, $0F, $1C. $14 


$15 


$13 


Print Manager 


$01-$04, $12, $06. $0E. $10, $0F, $14, 
$1C, $1B 


$15, 



For example, if your program uses any functions in the Line 
Edit tool set, it must start up in the following order: tool sets 
$01-$04 (Tool Locator, Miscellaneous tool set. Memory Manager, 
QuickDraw II), tool set $06 (Event Manager), and tool set $16 
(Scrap Manager). 

The First Six Functions 

Consistency has never been highly regarded in the computer pro- 
gramming world. But the Apple lies programmer will be delighted 
to know that the first six function calls in each tool set follow a 
standard format. These functions are housekeeping, or tool set 
management routines, and every tool set has them. 

As shown in the previous section, the StartUp function must 
be called before other functions in a tool set can be used. StartUp is 
just one of the first six functions. 

Apple Computer has reserved tool set functions $07 and $08 
for future enhancements. Until they are placed on the duty roster, 
the next usable function in each tool set is $09. 
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ID 


Function 


$01 


Bootlnit 


$02 


StartUp 


$03 


ShutDown 


$04 


Version 


$05 


Reset 


$06 


Status 



The first six function calls in each of the first six tool sets are 

as follows: 

Description 

Initializes the tool set for the first time 
Starts up the tool set for application usage 
Shuts down the tool set when no longer needed 
Returns the version number of the toot set 
initializes the tool set after a system reset 
Determines whether the tool set is active or not 

These function names are unique to each tool set since they 
are always prefixed by a short name. For example, the Memory 
Manager uses the letters MM before each of these function names: 
MMStartUp, MMVersion, and so on. The Tool Locator tool set uses 
TL: TLBootlnit, TLStartUp, and so on. 

• Bootlnit must never be called by an application. If the tool set is 
ROM-based, this function is performed when the computer starts 
up, If the tool set is RAM-based (loaded from disk), Bootlnit is 
called after it is first loaded into memory. 

• StartUp; As stated in the previous section, applications must call 
StartUp so that the tool set's functions become available. Some 
tool sets require input parameters for use with the StartUp func- 
tion. Passing parameters to a Toolbox function is discussed in the 
next section. 

• ShutDown must be called before exiting to the operating system 
when an application is finished with a tool set. The tool set would 
then free up any memory it had allocated and, in general, would 
clean up after itself. 

• Version: An application can determine the version number of a 
tool set by calling this function. It returns a word (16-bit integer) 
result. The high-order byte of the result consists of the major ver- 
sion number. The low-order byte contains the minor version. If 
the tool set is a prototype, bit 15 of the version number result will 
be set. (In this text when a bit is said to be set, it is made equal to 
1. A reset or cleared bit is one made equal to 0.) 

• Reset occurs when you press Control-Reset or make a DeskTop 
Bus reset call from software. The computer performs the Reset 
function in each of the active tool sets. 

• Status: A program can find out if a tool set has been started by 
making a call to it's Status function. If not active, it returns an 
integer value of 0, otherwise it returns a nonzero value. 
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Passing and Receiving Arguments from the Toolbox 

The majority of the Toolbox functions require an argument (a value 
or parameter) to be sent to the Toolbox, or they return an argu- 
ment, or a combination of both. The Toolbox works with three 
types of parameters: bytes, words (two bytes), and long words (two 
words). 

If any arguments are required by a function, they are pushed 
onto the processor's stack before the Toolbox call is made. Argu- 
ments returned from a function are then pulled from the stack after 
the call. This is demonstrated in the following portion of code 
which obtains the version number of the Miscellaneous tool set: 



pba 

ldi '10403 
J8l IE10000 

pla 



;puan space for the result 
;th9 MTVerslon function 
;call tbe Tooltrn 
;retriw« version Information 



The values returned from the stack must have space reserved 
for them before the call is made. This is done by pushing arbitrary 
values onto the stack. These values are replaced with useful infor- 
mation, pulled from the stack, after the call is made. 

The above function is handled as follows in C: 

Version = MTVerslon( ); 

Note that Version must be declared beforehand as a word 
value, an unsigned integer. After the call, the Version variable con- 
tains the version number of the Miscellaneous tool set. 

In Pascal, the function call is similar: 

Version = MTVersion; 

Remember to declare the variable, Version, as an integer. In 
both Pascal and C, the code for stack manipulation is provided by 
the compiler. 

When starting up the Memory Manager, a word-sized value is 
pushed onto the stack before the call to MMStartUp is made. This 
provides the result space for an ID number: 



pha 




:pueh space for the result 


ldx 


+♦0808 


;MMStartUp 


jsl 


♦E10000 




pla 




;pull the user ID 


sta 


User-ID 


;eave It In a safe place 
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When MMStartUp is called, not only does it allow access to 
other Memory Manager functions, it also assigns your application a 
unique identification number. You should store the value pulled 
from the stack as your program's User ID. You'll need it later on. 

The Memory Manager is covered in detail in Chapter 7. 

Direct Pages 

Many tools need only a call to their StartUp function to get them 
going. Others require additional information, such as timing infor- 
mation, graphics modes, the User ID returned by the Memory 
Manager's StartUp function, or a combination of these. 

A few tool sets require a small block of RAM to use as scratch 
space for their functions. This memory buffer is called a direct 
page, and it consists of one page (256 bytes) of RAM. The direct- 
page memory must exist in the first 64K bank of memory. 

Space for the direct page is allocated using a function in the 
Memory Manager. This function is called MewHandle. Since a pro- 
gram may use many tool sets and require a large quantity of direct- 
page space, it's common to allocate one large block of memory for 
use by each of the tool sets requiring direct pages. Therefore, you 
should calculate the total amount of direct-page memory needed 
before using the NewHandle function. See Table 4-1 for the 
amount of direct-page space each tool set requires, 

Once the direct page is established (by some sleight-of-hand 
programming you'll be reading about later), portions of it are di- 
vided among the tool sets which require them. 

Tools on Disk 

Some tool sets are stored in the SYSTEM/TOOLS subdirectory on 
the ProDOS 16 disk your computer is booted with. Tools on disk 
cannot be accessed until they have been loaded into memory. This 
is accomplished with the LoadTools function of the Tool Locator 
tool set. 

LoadTools uses a list of tool set numbers in memory to load 
corresponding files from disk. It accesses the disk and copies the 
tools into memory. 

When catling LoadTools, an application first pushes a four-byte 
address of the tool list to the stack. For example: 

pea Toolist I- 16 :push long word addreaa of list 

pea Toolist 

ldj *I0E01 ; LoadTools 

Jsl tElOOOO 
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Toolist (above) points to the memory location of the list of tool 
sets to be loaded from disk. The structure of the list of tool sets be- 
gins with a count word (two bytes) which tells LoadTools how 
many entries there are in the list. 

The count word is followed by several four-byte entries that 
describe the tools to be loaded. The first two bytes constitute a 
word that contains the tool set's ID number. For example, $0003 
would indicate the Miscellaneous tool set. The second two bytes 

arc a word that opecifiec the minimum v*rcion nf thu tnnl If a pro- 
gram requires version 1.3 or later of a tool set, $0103 is specified. 
By using a minimum version number of $0000, any version on disk 
will be loaded. 

The following is a sample table showing three tool sets to be 
loaded from disk: the Window Manager (tool set $0E), the Menu 
Manager (tool set $0F), and the Control Manager (tool set $10). 

Toolist dc I'JP ;count word (3 tool seta) 

dc I'*OE'.r00O<r ;W!ndow Manager 0.0 or newer 

dc MOP',1'0000' ;Menu Manager 0.0 or newer 

dc I'llO'.I'OOOO' ;Control Manager 0,0 or newer 

After the LoadTools call is complete, the program can proceed 
by starting up each of the loaded tool sets as needed, 

In C, the method of loading tools from disk starts by globally 
declaring an array of tool sets as a group of unsigned word-length 
integers: 

Word Toollst( ] = {3, /" Tool count •/ 

14, 0. /* Window Manager */ 

IB, 0, /* Menu Manager */ 

16. 0}; /' Control Manager '/ 

From within a function in your application, the LoadTools( ) 
function is called in this manner: 

LoadTools(Toollat): 

If you're using Pascal, the procedure is almost the same, except 
Toolist is defined in the VAR section of the program as a ToolTable 
type, a special record which follows the structure of the tool list: 

Toolist: ToolTable; 
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Unfortunately, Pascal forces the values in the Toolist array to 
be assigned at run time within a procedure. This results in longer 
code. Example: 

ToollsLNumToole : — 3; { Tool oount 1 

Tooll8t.Toota[l].TSNun> := 14; { Window Manager ] 
Too!lst.ToolB[l].MlnVeralon : = 0; 
TooliBt.Tools[2],TSNum :— IB; \ Menu Manager ] 
Tooll8t.Too]fl}2J.MInVBr8lQn := 0; 
ToollBt.ToolB(3J.T3Num := 16; { Control Manager } 
Tooll&t.ToolB[3].MinVerBlon := 0; 

Lo&dToolsCToollst); 

However, the LoadTools function call is identical in syntax to 

the call in C. 

When Errors Occur 

Calling some Toolbox functions can result in errors. Errors can oc- 
cur under a variety of circumstances. Not all of them are fatal. 

The way to tell whether there was an error during your Tool- 
box call is to test the carry flag after the function returns. If the 
carry flag is set, an error occurred, and your program can take ap- 
propriate action. If the carry flag is clear, no error occurred, and the 
program can continue. 

If an error does occur, the Toolbox places a special error code 
in the A register. This two-byte value describes the error that oc- 
curred and the tool set called. Unlike the Toolbox function num- 
bers, the tool set number in an error code is in the upper byte. The 
error number is in the lower byte. For example, if the error returns 
$0110 in the A register, the upper byte ($01) indicates that the er- 
ror occurred with tool set $01, the Tool Locator. The error code 
($10) is in the lower byte. Error code $10 of the Tool Locator is 
Mimmum Version Not Found. (All error codes are documented along 
with the Toolbox functions in COMPUTED Mastering the Apple IlGS 
Toolbox.) This error might occur when the LoadTools function is 
called to load tool sets from disk into RAM. If the minimum ver- 
sion specified is not found on disk, this error is returned after the 
LoadTools function is called. 

Note that only some of the functions in the Toolbox result in 
actual errors. Some are unable to produce errors, yet may return 
with the carry flag set. An application should only test for errors 
after making Toolbox calls capable of producing errors. 
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Trapping for Toolbox errors in a C program is done by testing 
an external variable called -toolErr {note the underscore). This 
variable is declared as type extern in the types.h header file, which 
should be the first file included by any C program that uses the 
Toolbox, If —toolErr is a nonzero value, it means that the most re- 
cent Toolbox function resulted in an error. The value in -toolErr is 
the error code. 

Here is a sample error-handling statement in C: 

If (-toolErr) SyaFallMgK-taolErr, nil); 

Care should be taken when handling errors in C by referenc- 
ing the _toolErr variable. Since this variable is changed after each 
function call, your program should make a copy of —toolErr before 
using any other Toolbox functions. 

TMl Pascal programmers handle errors in a similar fashion. To 
see if an error has occurred, the value of a predefined variable 
called IsToolError is tested. The error code is stored in another 
predefined variable called ToolErrorNum. 

Here is a sample error-handling statement in TMl Pascal: 

IP IaToolEfPOr THEM 1 

Sy8FallMgr(ToolEfrorNum, 'Fatal system error — > •'); 

All the examples for handling errors, shown here, take the 
easy way out, The Miscellaneous tool set includes a function called 
SysFailMgr which brings up the familiar sliding Apple error mes- 
sage screen. (You see it when you try to boot the Apple IlGS with- 
out a disk in the drive). 

SysFailMgr is adequate for testing purposes, but it shouldn't be 

used when errors occur in end-user or commercial applications. 

There are elegant (and user-friendly) ways of handling errors. It 
just takes a little extra effort to incorporate them into your 
programs. 

Closing the Toolbox 

When an application is finished using a particular tool set, it should 
shut it down. This is done by calling the tool set's ShutDown func- 
tion, number $03. For example, to shut down the Menu Manager, 
the MenuShutDown call is made: 



ldl **030F 
Jal IE10000 
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Since an application uses many tool functions throughout the 
running of the program, tool sets are usually shut down all at once 
before the program quits. 

As a rule, tool sets should be shut down in the reverse order 
that they were started up. If, for example, the Miscellaneous tool 
set was shut down before other tool sets, it would cause the appli- 
cation to crash. 

The Memory Manager is one of the last two tool sets to be 
shut down just before a program ends. Before the MMShutDown 
call is made, all allocated memory handles associated with an 
application should be disposed (that is, those requested for direct- 
page space). The easiest way to do this is with the DisposeAll 
function: 



Ida 


MemlD 


; Identify the blocks 


pba 




;. . . by their ID numbers 


ldi 


**1102 


iDlaposeAll (memory handles) 


Jul 


IE10000 





This disposes of all memory handles allocated by the applica- 
tion (identified by the MemlD value). DisposeAll should never be 
used with the UserlD value that was returned by MMStartUp, 

Handles, doled out by the Memory Manager's NewHandle 
function, can be disposed of one at a time. This example demon- 
strates how easily a handle can be removed from C or Pascal: 

Dl8pofleHandl6(MyHandl9); 

When memory handles are disposed, the space they occupied 
is freed and is made available to other applications. More details on 
memory management are discussed in Chapter 7. 

Once all the memory handles allocated by your program are 
disposed, the MMShutDown function can be called. 

Chapter Summary 

The following Toolbox functions were referenced in this chapter: 

Function: Sui-d I 
Name: LoadTools 

Loads a list of tools from disk into RAM 
Push: Tool List Address (L) 
Pull: nothing 
Errors: $0110 Version Error; possible ProDOS errors 
Comments. The list of tools starts with a count word. 
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Function: 

Name: 

Push: 
Pull: 

Errors: 
Comments: 

Function: 

Name: 

Push: 

Pull: 

Errors: 

Function: 

Name: 

Push: 

Pull: 

Errors: 

Comments: 

Function; 

Name: 

Push: 

Pull: 

Errors: 

Comments: 

Function: 
Name: 

Push: 
Pull; 

Errors: 
Comments: 

Function: 

Name: 

Push: 
Pull: 

Errors: 
Comments: 



$0302 

MMShutDown 

Shuts down the Memory Manager 

User ID (W) 

nothing 

none 

The User ID is obtained when MMStartUp is first called. 

$1002 

DisposeHandle 

Disposes of a handle and the memory block it references 

The Handle (L) 

nothing 

$0206 (invalid handle) 

$1102 

DisposeAll 

Disposes of all memory handles associated with an ID 

User ID (W) 

nothing 

$0207 (invalid User ID) 

Do not use with the program's master User ID. 

$0203 

MTStartUp 

Starts up the Miscellaneous tool set 

nothing 

nothing 

none 

This call must be made before any Miscellaneous toots can be 

used. 



MTVersion 

Returns the version number of the Miscellaneous tool set 

Result Space (W) 

Version (W) 

none 

MSB is major release; LSB is minor release. 

$1503 
SysFailMgr 

Displays an error message and halts the program 
Error Code (W), C-String Address (L) 
nothing 
none 

A standard message is displayed if the string address param- 
eter is 0. 
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Function: S2C03 
Name: SysBeep 

Beeps the Apple IlGS speaker 
Push: nothing 
Pull: nothing 
Errors: none 

Function: S030F 

Name: MenuShutDown 

Shuts down the Menu Manager 
Push: nothing 
Pull: nothing 
Errors: none 



Chapter 5 

A Matter of 
Language 

As stated earlier, this book as- 
sumes that you have a strong 
background in programming 
languages, either machine lan- 
guage, Pascal, or C. This isn't a 
tutorial on programming, 

Yet there's more to using a 
programming language and 
developing software than just 
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knowing the meaning of such terms as ASL, printf, or begin. There 
is a wealth of programming information to learn once you under- 
stand the basics. This information will make you a better program- 
mer. The purpose of this chapter is to fill you in on some of the 
finer points of programming the IlGS, no matter which language 
you use. 

This chapter offers programming hints and tips for the three 
languages covered in this book, On the following pages, you will 
find helpful information and suggestions for making programming 
and developing applications for the Apple IlGS computer much 



Take Life a Little Easier 

Because this chapter tries to cover three very different program- 
ming environments, extra care was taken to ensure that everything 
was presented properly. To do that, this chapter is divided into two 
sections. The first section covers support files for all three lan- 
guages, and the second deals with each language individually. 

Support files, though they may be referenced by each language 
differently, are common to all three programming environments, 
Most amateurs avoid using support files because they don't under- 
stand them, which is a big mistake. By taking advantage of support 
files, you can save time and massive headaches. You should take 
the time to learn about support files. 

The second part of this chapter concentrates on each program- 
ming language individually: The APW Assembler, TML Pascal, and 
C are each given a separate section. The purpose of the second half 
of this chapter is to help you use the language you have chosen to 
its full potential. After reading about Support Files, skip to the sec- 
tion on the language that interests you. 

Of course, the adventurous reader will want to read every- 
thing: If you are only fluent in one or two languages, you may be 
surprised to find out what you are missing. 

Support Files 

To smooth the process of writing applications, the makers of APW 
and TML Pascal have created scores of utility and support files. 
These files typically contain defined routines, macros, or subroutine 
libraries. By taking advantage of support files, you can decrease 
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development time and, at the same time, make your program easier 
to read and better looking. 

In machine language, support files contain common routines 
and functions written as macros. For example, to avoid the redun- 
dancy of making Toolbox calls by loading the X register and per- 
forming a long jump to the subroutine at $E 10000 each time a call 
is made, a Toolbox macro support file can be used instead. This 
support file already contains the defined Toolbox calls. All your 
source needs to do is reference the specific support file. 

TML Pascal support routines, which include Apple IlGS Tool- 
box calls and other Pascal -oriented functions, are stored in sym- 
bolic unit files. These files end with a .USYM extension on disk. 
The USES keyword tells the compiler to use the unit file that corre- 
sponds to functions used in your program. 

The #include directive is used to insert a source file into the 
compilation step when compiling a C program. Support files for C, 
called header files, end with a h extension on disk. Since files used 
with #indude can contain any instructions at all, they are far more 
flexible than Pascal's compile-time unit files. 

The following tables illustrate how your source code could 
take advantage of predefined QuickDraw II functions. The follow- 
ing are QuickDraw 11 support files, each of which can be referenced 
by your code. 
Language Directive Support Filename 



APW Assembler 


MCOPY 


M16.QUICKDRAW 


TML Pascal 


USES 


QDlntf 


APWC 


#include 


quickdraw.h 



In your source code, the above directives might take on the 
following syntax: 

Language Syntax 

APW Assembler MCOPY 2/AINCLUDE/M16.QUICKDRAW 

TML Pascal USES QDlntf; 

APW C #include <quickdraw.h> 

After these statements, your source code could then use the 
QuickDraw II functions defined in the appropriate support file. 
(This will be explained in greater detail below, under each lan- 
guage's category.) 

When programming high-level languages such as C and Pas- 
cal, these support files must be included in the compilation phase 
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of your program to use them. Otherwise, you'll receive an unde- 
fined junction call error message. It's best not to argue with the 
compiler if you want your code to run. 

Macros are not required in order to make machine language 
Toolbox calls. The programmer can use the corresponding 65816 
instructions if desired. However, using the macros defined in the 
APW Toolbox support files is accepted and a more common practice 
than writing out the necessary code. 

The most common use for support files is to define Toolbox 
calls. Each tool set in the Toolbox has an associated support file. 
There are several other specialty and utility files, depending on 
your language, which can also be used to simplify writing 
applications. 

Table 5-1 shows the support files that belong to each tool set 
for machine language, C, and Pascal. 

Table 5-1. Tool Set Support Files 





APW Assembler 


APW C 


TML Pascal 


Tool Set Name 


(MCOPY) 


(♦include) 


(USES) 


Tool Locator 


M16.LOCATOR 


locator.h 


GSIntf 


Memory Manager 


M16.MEMORY 


memory.h 


GSIntf 


Miscellaneous Tools 


M16.MISCTOOL 


misctool.h 


MiscTools 


QuickDraw 11 


M16.QUICDRAW 


quickdraw.h 


QDlntf 


Desk Manager 


M16.DESK 


desk.h 


GSIntf 


Event Manager 


Ml 6. EVENT 


event.h 


GSIntf 


Scheduler 


M16.SCHEDLLER 


scheduler. h 


Scheduler 


Sound Manager 


M16.SOUND 


sound, h 


Sound 


DeskTop Bus 


M16.ADB 






SANE 


M16.SANE 


sane.h 


SANE 


Integer Math 


M16.1NTMATH 


intmath.h 


IntMath 


Text Tool Set 


M16.TEXTTOOL 


texttoolh 


TextTools 


Window Manager 


M16.WINDOW 


window.h 


GSIntf 


Menu Manager 


M16.MENU 


menu.h 


GSIntf 


Control Manager 


M16.CONTROL 


control.h 


GSIntf 


System Loader 


M16.LOADER 


loader.h 


Loader 


QuickDraw H Aux. 


M16.QDAUX 


qdaux.h 


QDlntf 


Print Manager 


Ml 6. PRINT 


print. h 


PrintMgr 


LineEdit 


M16.L1NEEDIT 


lineedit.h 


GSIntf 


Dialog Manager 


M16.D1ALOG 


dialog. h 


GSIntf 


Scrap Manager 


M16.SCRAP 


scrap.h 


GSIntf 


Standard File 


M16.STDFILE 


scdfile.h 


GSIntf 


Disk Utilities 









1 



64 





APW Assembler 


APW C 


TML Pascal 


Tool Set Name 


MCOPY) 


(#include) 


(USES) 


Note Synthesizer 


M16.NOTESYN 


notesyn.h 


NoteSyn 


Note Sequencer 


M16.NOTESEQ 






Font Manager 


M16.FONT 


font.h 


GSIntf 


List Manager 


M16.L1ST 


list.h 


LisrMgr 



Depending on the language you're using, there might be addi- 
tional support files for working with ProDOS or a shell environ- 
ment. Check your language's reference manual for more details. 

At the time of this writing, some of the tool sets do not have 
support files, most notably those still being worked on by Apple 
Computer. 

Although TML Pascai's unit symbol files end with a .USYM ex- 
tension on disk, do not include the extensions in the USES state- 
ments in your program. 

In addition to the above assembler macro files, the APW as- 
sembler can also take advantage of equate files. These, like macro 
files, are text files that contain some of the constants and symbols 
listed in the Toolbox reference, For example, wAmBooli is a flag 
used by one of the tool sets. If your source code were using 
wAmBooli, as in 

PEA 'wAmBooli 

and if the equate file for that tool set were referenced by your 
source code with the COPY directive, then the assembler would re- 
place wAmBooli with the proper value. 

Table 5-2 lists the support files for equates to be used with 
APW source code. Like the macro files, they are found in the 
LIBRARIES/AINCLUDE subdirectory. 

Table 5-2. Assembler Equate Files 

Tool Set Name 
Tool Locator 
Memory Manager 
Miscellaneous Tools 
QuickDraw II 
Desk Manager 
Event Manager 
Scheduler 
Sound Manager 
DeskTop Bus 
SANE 



Equate File 

El 6. LOCATOR 

E16.MEMORY 

E16.MISCTOOL 

E16QUICDRAW 

E16.DESK 

E16. EVENT 

E16.SCHEDULER 

E16.SOUND 

E16.ADB 

E 16. SAKE 



- 
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Tool Set Name 

Integer Math 
Text Tool Set 
Window Manager 
Menu Manager 
Control Manager 
System Loader 
QuickDraw II Aux. 
Print Manager 
LineEdit 
Dialog Manager 
Scrap Manager 
Standard File 
Disk Utilities 
Note Synthesizer 
Note Sequencer 
Font Manager 
List Manager 



Equate File 

E16.INTMATH 

E16.TEXTTOOL 

E16.WINDOW 

E16.MENU 

E16.CONTROL 

E16.LOADER 

E16.QDAUX 

E16.PRINT 

E16. LINEEDIT 

E16. DIALOG 

E16.SCRAP 

E16STDFTLE 

E16.NOTESYN 

E16.FONT 
E16.LIST 



Note: The Disk Utilities and . r equate files were not included in version 1.0 of 

the APW assembler. 



Individual Languages 

The way each language takes advantage of its support files is dis- 
cussed in the following sections. 

The C Language Environment 

C is an elegant language, but don't let its elegance fool you. It's a 
nuts-and-bolts programming language- C has the detail of machine 
language, while retaining some of the conveniences of the high- 
level languages. Anyone trained in BASIC and then forced into ma- 
chine language because of BASIC'S crudity and slowness will enjoy 
C. 

The road from your first Hello World C program to a complete 
application on the Apple IIGS should be smooth. Even though the 
APW C development system isn't as flashy as other programming 
environments, it can be used to develop large and complex applica- 
tions. In fact, most of the new IIgs programs that originated on 
other computers are written in C, simply because the original 
source code can be moved to the IIGS with only minor modifica- 
tions, in most cases. 
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Support files for APW C are kept in the LIBRARIES/CINCLUDE 
area on your APW program development disk, They all end with .h 
extensions because they are known as header files. This means that 
they should be included in your source code, with the #include di- 
rective, at the top (or at the head) of your program. 

The following is an example of how to use a support file in a 
C program: 

/* Including Header Piles In C— Klnda Boring •/ 

•Include <locator- h> /* Include the Tool Locator header file */ 

maln( ) 



TLStartUp( ); 
TLShutDown( ); 



/■ Stan the Tool Locator 7 

/' Shut It down ASAP '/ 



All the definitions for the Tool Locator functions are kept in 
the locator.h header file. By including this header file, the 
TLStartUp, TLShutDown, and other Tool Locator routines can be 
accessed by the C program. The same is true for any other tool set 
that your program uses. Include the header file for each tool set 
you intend to use. 

•include <locator,h> 

•Include <memory.h> 
•Include <mlflotool.h> 

The MODEL. C program, introduced in Chapter 6, has some 
real-life examples of support files in use. 

The Pascal Environment 

Pascal (not to be confused with UCSD Pascal, an early Apple op- 
erating system) is famous because of its structure. In fact, most 
educational institutions prefer to teach programming with Pascal 
because it forces the student to think logically and to break a prob- 
lem down into smaller, easier-to-solve tasks. 

Currently, the only Pascal compiler for the Apple IlGS is the 
one from TML Systems of Jacksonville, Florida. It's more than just 
a compiler. In fact, TML Pascal is a complete and powerful 
program-development system. 

Support files for the APW version of TML Pascal are kept in 
the TOOLINTF area on your APW disk. The regular TML Pascal al- 
lows you to define where the unit files are stored. They all end 
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with .USYM extensions because they are known unit symbol files. 
Rather than being included as source code as is done in C, unit 
symbol files are USED in TML Pascal. Here's an example: 

{ Using Unit Symbol Files In Paaoal } 

PROGRAM Yawn: 

USES QDIntF, GSIntF. MlscTools; 

BEGIN 

TLStartUp; 

TLShutDown; 
END. 

The USES section of the Pascal program tells the compiler to 
use the unit symbol files included in the list. The corresponding 
functions for each tool set then become available for your program 
to work with. 

TML doesn't intend to stop with Pascal. At this writing, they 
are about to release a BASIC compiler for the Apple 1IGS. 

The Machine Language Environment 

If you're doing machine language development, you're probably 
using APW, the Apple Programmer's Workshop. So far, it's the most 
popular machine language development environment for the Apple 

lies. 

To use the APW Assembler effectively, you'll need at least two 
disk drives, or one 3VWnch disk drive and a very large ramdisk of 
about 800K. The APW programs should be on one disk with your 
source code and any other files you need on the other. However, 
the best setup for any serious programming involves a hard disk 
with at least ten megabytes of storage. When this is the case, APW 
and all its files should be put in their own subdirectory. 

The latest version of APW requires at least 768K of RAM on 
your computer, which is 512K more than the 256K that comes with 

the Apple IlGS . 

When developing programs, its best not 10 put all uf youi 
code into one, huge, cumbersome file. In fact, the best way to pro- 
gram is to keep your source code in small, separate modules. Not 
only will this help you keep track of updates (by checking the date 
column in a catalog listing), but it will reduce the time it takes to 
patch code. 

The rest of the machine language examples in this book will, 
where applicable, use the modular concept to add pieces to the 
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MODEL.ASM program demonstrated in the next chapter. You can 
make decisions about how many modules to make, and what size 
to make them, on your own. 

Modules are added, or chained, to one another by use of the 
COPY directive. For example, if the MODEL.ASM program refer- 
ences two other modules, DISKIO.ASM and WINDOW.ASM. the 
following directives should be placed at the end of the source code: 



COPY 
COPY 



DISKIO.ASM 
WINDOW.ASM 



. 



This will copy the source code from those two files to create 
the final program. 

It is helpful to know that you're not chained to the APW Edi- 
tor, considered by many to be a simple-minded text editor. By the 
time you read this, there should be several good public domain or 
shareware text editors on the market, any one of which could be 
used to edit APW source files. 

Using APW is similar to using MS-DOS or UNIX. However, 
programs created under APW are not directly executable by the 
Finder or Launcher. You must change their filerype from an EXE 
(SB5) to a S16 ($B3) file type. This is done with the FILETYPE 
command at the APW system prompt. For example, 

FILETYPE MODELA S16 

changes the file type of the MODELA program from EXE to SI 6, 
allowing the program to be run directly from the Finder or 
Launcher. 

Other than that, APW is straightforward and easy to use, con- 
sidering that you're writing machine language. However, there is 
one more detail about the APW: Machine language programmers 
should pay special attention to the way the APW assembler uses 
macros. 

Macros. Macro is a an abbreviation of macromstructiot}. A 
macro is used to represent a number of other statements, like an 
abbreviation. Some complex macros can even make decisions and 
perform evaluations. Yet, you only write the macro instruction 
once. Then, from that point on, you use only the name o( the 
macro to reference it. 

You probably won't find any machine language examples in 
any books that don't use macros {other than Mastering the Apple 
IlGS Toolbox, where macros were not used in order to better explain 
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certain concepts). Because of this fact, all the machine language 
source code in this book uses macros. You'll find that macros make 
programs easier to read and easier to write. For this reason, the rest 
of this chapter is devoted to APW machine language macros and 
how to use them. 

Macro etiquette. Macros are most commonly used to make 
Toolbox calls With the APW assembler, the convention for Toolbox 
macros is to start them with the underscore character as in the fol- 
lowing example that invokes the MoveTo Toolbox call: 

^MoveTo 

Case is unimportant as far as macros are concerned, unless 
you've specifically told the APW assembler to pay attention to case 
by using the CASE ON directive. Each of the following lines will 
invoke the MoveTo macro (assuming you have not used the CASE 
ON directive): 

„moveto 

_MOVET0 
_MoVftTo 

All Toolbox calls have a macro, as defined in the support files 
in the LIBRARIES/AINCLUDE subdirectory. And all Toolbox mac- 
ros carry the same name as their Toolbox function, with each pre- 
ceded by an underscore. 

Aside from the Toolbox calls, several other APW assembler 
macro types are popular. The ones most often seen are these: 

Macro Action 

PushLong Push a long-word value onto the stack 
PushWord Push a word value onto the stack 
PullLong Pull a long-word value from the stack 
PullWord Pull a word value from the stack 
Str Create a Pascal string 

There are some distinct advantages to using the PushLong and 
PushWord macros over the PEA instructions. The most common is 
the error that occurs when a memory location rather than a value is 
pushed to the stack (PEA $1234 instead of PEA #$1234). If you use 
the PushLong and PushWord macros, there will be no question 
about which type is being pushed. 

Also, the Str macro eliminates some of the tedious labeling 
that occurs when defining a Pascal string. (Pascal strings start with 
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a count byte to tell the program how many characters to expect.) 
Because Pascal strings are used frequently in the Toolbox, the Str 
macro is very handy. 

Macros at work. When the assembler sees your macro, it ex- 
pands the macro into the code it stands for. This is one of the most 
confusing aspects of using macros, 

Macros make the source code easier to read and easier to de- 
bug. They help the programmer avoid redundancy by eliminating 
the need to type the same code repeatedly. A beginning machine 
language programmer might assume that using macros tightens up 
code. That's only half true: Macros make your source code tighter, 
but your object code will be just as long as if you didn't use 
macros. 

When your source code is assembled into object code, the mac- 
ros you use are expanded out into their raw form. So for each 
—MMStartUp the assembler sees, it replaces it with the appropriate 
code: 

Idl '10202 

]Sl »E10000 

Macros can be simple (as above) or complex. For example, a 
macro can look rather innocent in the middle of your source code: 

PuBhLong *1234 

The PushLong macro is much more complex than —MMStartUp, 
PushLong will be translated by the assembler into the codes de- 
Fined in the macro. Because there can be a number of arguments 
for PushLong (a value, a memory location, or a zero-page location 
plus an offset, the stack plus an offset, and so on), the PushLong 
macro must make a few decisions. 

The actual definition for the PushLong macro is quite complex: 

MACRO 
cfelab pushlong &addr.&otfs6l 
ftlat) AMOP 

LCLC *C 

LCLC &RBST 

ftC AMID ftaddr,l,l 

AIF *C=*. Immediate 

AIF &C — [..zeropage 

AIF C:froffaet = 0,.nooffael 

AIF &offeet=8,.atack 
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puehword 


&addP + 2,fioff8et 


pushword 


&addp,*o(f88t 


MExrr 




.nooffset 




puahword 


&addr+2 


puahword 


&addr 


MEXIT 




.Immediate 




te REST AMID 


&addr,2,L:&addr-l 


dc 


ir«74'.I2'(&REST)l-16 


do 


I^^P4'.I2■4rREST , 


MEXIT 




ataols 




puahword 


&addr + 2.e 


puehword 


&sddr+2.s 


MEXIT 




zeropage 




Idy 


»&Ol[BBt+2 


puahword 


feaddr.y 


Idy 


'^offset 


push word 


fcaddr.y 


MEND 





Inside PushLong's definition are conditional branches and 
evaluations to determine exactly what type of long-word value is 
being pushed on the stack. The assembler, when it replaces the 
macro PushLong with the above instructions, will make certain 
evaluations and then use only those instructions to push the proper 
long value onto the stack. 

For example, if 

PuehLong *1234 

is specified in your source, the assembler will use the following in- 
structions from the PushLong macro to push #1234 onto the stack: 



+ ANOP 




+ LCLC 


*C 


+ LCLC 


*REST 


+ 4C AMID 


•1*84,1,1 


+ . immediate 




+ SrREST AMID 


*1234,2,L;&addr— 1 


+ do 


irtF4',I2'{1234)l-18' 


+ dc 


\VtF4\WU3V 
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That seems like a very complex procedure to go through just 
to push a long word on the stack, yet some complex decision mak- 
ing is occurring. For PushLong to be a versatile macro, capable of 
pushing a variety of values onto the stack, it has to be complex. 
Fortunately, the logic and debugging of the PushLong macro has 
been taken care of for you. You need only specify it in your source 
and let the assembler do the rest. 

To see how a macro expands, the TRACE ON directive can be 
listed at the top of your assembler source. By adding the LIST ON 
directive, you'll be able to see your source code as it's assembled 
and, with TRACE ON set, see the macros expanded as well. 

Using macros in your source code. With the APW Assembler, 
macros exist in an external file and are referenced in your source 
code by the MCOPY directive: 

MCOPY (pathname] 

The pathname is the name of a path or file that contains all 
your program's macro definitions. For example: 

MCOPY MYMACROS 

The above instruction directs the assembler to look for any 
macro references in the file MYMACROS. Make sure you have this 
statement at the top of your source code. The macros used by your 
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source can 
MCOPY command. 

So, if your source code makes extensive use of QuickDraw II 
Toolbox calls, and you want to use the QuickDraw II macros sup- 
plied with APW, you could place the following at the top of your 
source code: 

MCOPY /APW/LIBRARIES/AIKCLrjDE/M16.QUICKDRAW 

Because APW takes advantage of ProDOS 16 prefix numbers, 
you can substitute the number 2 for /APW/LIBRARIE5 above. (No 
matter what the configuration of your drive, using 2 will work. See 
the section in the APW manual about the LOGIN file for more 
information.) 

MCOPY 2/AINCLUDE/M16.QUICKDRAW 

After using this instruction, any QuickDraw II macros refer- 
enced in your source code will be replaced by the definitions in the 
MI6.QUICKDRAW support file. 
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This sounds like a powerful feature when you're reading the 
APW Assembler manual and might cause you to think you could 
just MCOPY all the predefined macros in the AINCLUDE subdirec- 
tory into your source code. While that sounds logical, and it would 
make things easier, it's just not the case. 

The MCOPY command only allows four macro files to be in 
use at one time. The manual seems to suggest that you can juggle 
these four macro files using the MLOAD and MDROP directives 
throughout your code. However, this is a fallacy. Rather than toss 
about MCOPY, MDROP, and MLOAD directives, it's much faster 
and easier to create a custom macro file for your source code files. 
This is done with the MACGEN program from the APW shell: 

MACGEN [soupo&.oods] [macro.flle] [macro-llbrarles , . .] 

MACGEN creates a custom macro file for your source code. 
It's one of APW's better utilities. 

First, MACGEN reads in your entire source file. Then, it scans 
a specified list of macro support files, pulls out only the macros ref- 
erenced by your source code, and finally creates a custom macro 
file containing only the macros referred to by your source. 

For example, consider the program MODEL, ASM in the next 
chapter. MODEL makes extensive use of macros. Most of those 
macros are defined by the M16 files in the A1NCLUDE prefix. To 
build a custom macro file containing only the macros referenced by 
MODEL.A5M, the following MACGEN command was typed at the 
APW system prompt: 

MACGEN modeLaam model. macroB 2/alaclude/ml8. — 

This reads: From the source code model. asm, generate a macro 
file named model.maeros using all the files that start with ml 6. in 
the subdirectory AINCLUDE. (The equal sign is a wildcard specify- 
ing all files starting with M16.) 

MACGEN reads in the source code and then reads through all 
the files Ml 6.= for any matching macros. It then places the macros 
it finds into the file MODEL.MACROS. To take advantage of them, 
the following is placed at the start of MODEL.ASM: 

MCOPY MODEL.MACROS 

If your program has more than one module, you should use 
the MACGEN command on the main module. As long as the main 
module has COPY or APPEND directives, the other related source 
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file modules will also be scanned for macro references. 

Building a custom macro file with the aid of MACGEN is the 
best way to provide the macros your program needs. If you update 
your source listing with new macro calls, you can run MACGEN a 
second time to create a new custom macro file. Also, any unique 
macros you create can be typed into the macro file using the APW 
editor. 

Summary 

Macro files, header files, unit symbol files, nearly all the information 
covered in this chapter can be found elsewhere. However, many 
people who consider themselves old hands at programming have 
never taken advantage of support files. With the Apple IlGS Toolbox 
at your disposal, using support files and paying attention to the tips 
offered in this chapter can make you a better programmer. 
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The DeskTop 

Applications for the Apple IlGS 
fall into two categories: Desk- 
Top and non-DeskTop. This 
chapter introduces some new 
and exciting things happening in 
the DeskTop world of program- 
ming. It begins with a descrip- 
tion of a DeskTop program and 
provides a sample program, in 
three languages, that you can 
run on your computer. 




— Chapter 6 

The DeskTop 

A DeskTop program is one that takes advantage of the 16-bit pro- 
cessing power of the Apple IlGS and uses its built-in tools to manip- 
ulate pull-down menus, windows, dialog boxes, icons, the mouse, 
and so on. This interface has proven to be highly intuitive to the 
user and is popular on a variety computers. DeskTop programs 
written for the Apple IlGS will not run on the Apple He or lie. 

A non-DeskTop program is one written for the eight-bit 
personality of the Apple IlGS. This half of the computer, also called 
the Mega II, emulates an Apple He with 128K of RAM and a 65C02 
processor. Programs in that environment rarely use the powerful 
tools that reside in the Apple HGS Toolbox ROM. They are required 
to provide their own memory-management schemes and custom 
interfaces. This entails a lot of work for the programmer. However, 
these programs can run on the Apple IlGS as well as on the Apple 
He and lie. 

Having a "canned interface" inside the computer provides 
many advantages. Users feel at home with DeskTop programs be- 
cause the interface is consistent from one program to the next. Pro- 
grammers can concentrate on the tasks of their software and are 
spared the details of interacting with the user. Since most of the 
code for the interface resides in ROM, programs require only a few 
calls to drive the entire DeskTop. 

The DeskTop interface, remarkably similar to that found in 
Apple's Macintosh computer, is the most exciting aspect of the Ap- 
ple IlGS. 

Managers 

Here's a quick description of the Apple IlGS DeskTop and how the 
various managers built into the IlGS are responsible for maintaining it. 

When a DeskTop program is first launched, a blank back- 
ground pattern is displayed across the entire Apple IlGS super-hi- 
res graphics screen. Traditionally, the background pattern is a solid 
shade of light blue, though the programmer can choose any color 
supported by computer. 

Inevitably, the DeskTop will have a menu bar at the top of the 
screen which contains the titles of one or more pull-down menus. 
These menus contain all of the program's commands and functions 
available to the user 
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Figure 6-1. Figure of DeskTop with Menus, Dialog Boxes, and 
Windows 



t File Edit Utem Special l »>inr It 




It is the responsibility of the Event Manager to track the loca- 
tion of the mouse and update the mouse pointer on the screen. The 
mouse pointer, an arrow shape, marks the position on the screen 
where the mouse is located on the DeskTop. Moving the physical 
mouse device will cause the mouse pointer to move accordingly on 
the screen. This function is completely transparent to the DeskTop 
application because it relies on the interrupt feature of the Apple 
IlGS microprocessor. 

The mouse is used to select items on the DeskTop. For ex- 
ample, the user moves the mouse pointer over a title on the menu 
bar and presses the mouse button. This causes a pull-down menu 
to be displayed, showing a list of available selections. By holding 
down the mouse button and moving the pointer (an action called 
dragging) the user chooses a menu item from the menu. A selection 
is made when the mouse button is released. 

The programmer organizes what is to be placed into the 
menus and passes that information along to the Menu Manager. 
The job of drawing pull-down menus and interacting with the user 
while a selection is made is handled completely by the Menu Man- 
ager. To do this, of course, it relies on other tool sets, especially 
QuickDraw II. 
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Some menu items are selected with the keyboard instead of 
the mouse. This is done by pressing the Open Apple key in con- 
junction with another key that corresponds to a menu item. The 
user determines if a menu item has a keyboard equivalent by 
examining the list of items in a pull-down menu. Menu items with 
keyboard equivalents have apple symbols, followed by the com- 
mand character, after their name in the menu. 

For the programmer, all of the work involved in getting the 
user's selections via the mouse or keyboard equivalents is handled 
by the routines in the Toolbox. It's the job of the Window Manag- 
er's TaskMaster function to manage these details. 

After a menu item is selected, any number of events might oc- 
cur As an example, a dialog box could be displayed asking the 
user to supply input for the application. Appropriately named, dia- 
log boxes let the user communicate with the DeskTop program by 
filling in blank entries with text, turning switches on or off, press- 
ing buttons, or by using other controls. 

Using software, the programmer builds the dialog box to the 
required specifications. Buttons and other controls can be installed 
on the box. The functions in the Dialog Manager and Control Man- 
ager allow the user to manipulate the controls and report to the 
application which buttons have been pressed, 

The function of a typical DeskTop program is as simple as 
making a selection from a vending machine. Tbe user makes selec- 
tions from the menu bar and interacts with a few dialog boxes, and 
the computer performs its assigned task. 

The Apple IlGS has more managers than a small baseball 
league. The programmer is well assisted in driving the DeskTop. 

Parts of a DeskTop Program 

At the software level, DeskTop applications consist of three main 

parts: 

Startup Before a program can begin to interact with the 

user, it must complete the startup phase. This in- 
volves starting a host of tool sets, allocating mem- 
ory, and setting up the DeskTop environment 
with pull -down menus and so forth. 
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Event handling Once everything is initialized, a DeskTop program 
basically sits idle, waiting for the user to make se- 
lections from the pull-down menus. When a menu 
item is selected, a corresponding function for that 
item is dispatched and carried out. 
Eventually, the user will be finished with the pro- 
gram and will want to quit. As part of the shut- 
down process, the application will take care of 
unfinished business, such as saving changes to 
disk. It shuts down the tool sets it started up, 
deallocates reserved memory, and exits to the op- 
erating system. 

These three steps provide the basic framework of practically 
every DeskTop program written. The nice thing about this is that 
once you've created the overhead code (the basic code that performs 
these three functions), it can be used over and over again for new 

programs. 

The Tower of Babel 

The following sample program — shown here in APW machine lan- 
guage source code, APW C, and TML Pascal— demonstrates how a 
typical DeskTop program starts up, handles events, and shuts 
down. It doesn't do anything spectacular. But it sets the stage for 
some very exciting programming ventures using the powerful abili- 
ties of the Apple lies Toolbox. 

Referring to these programs as models, the next few chapters 
will describe the important details in creating DeskTop programs. 
Study closely the program listing written in the language you're 
most interested in. 

Program 6-1. MODEL.ASM 



MODEL. ASM 
Sanpie DeskTop Application in Apv Assemcier 



Mte tne Moae I Macs macro tile, use thi3 APW shei 
a macoen moo*.. asm moo* i macs 2/ainclude/m= 

A&SAODR ON 

KEEP MooeiA 

HCOPV nooe lilacs 



Glooai Equates 
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Tooioox qequ SelQQQQ 

TRUE genu »800fj 

FALSE 9#<3Vj *>0Q° 

?i9# 9eiu »* 0u 

HOOtlA START 
pnk 

plD 

DC I Ma i n 



;Primarv tool dispatcher 

sTrue value 

;FalS* value 

;The sue Of a page 1256 DytesJ 



:Hake the data banK.. . 
;,.,the current code Dan* 
-.Branch over tu.net ions to Ham 



. Handle Toolbox Errors 



ErrChk oca 



Die 



Die pha 

push long «u 
jSysFaiIHgr 



:Carry set if error 

;Else. return 

-.Tooioox returns error in A 

jllse standard system death message 

:G«t ready to slid* apples eac* ana forth 



• Manage Direct Page Buffers » 

^^rns'^re^^rn^rirerD.reet Page .Modifies Vreg,« er > 
J The GetDPs entry point requ,." byte =oun< in * rwiitpr. 



Get DP loa 

OtDPs clc 

Idy 

add 

tya 

ret 



•Page 



;A9* for oae 256 Dyte DP DlocK 
Alternate entry: A = Numwr of DVtes 
np H ,„ ;Get base value twe return this) 

Kse.DPi.ase :Add A to our last DP buffer address 
ifceturn entry value 



Start Up Tools 



DPSpace equ SO 00 600 

HndlRef equ »00 

StartUpTools anop 
jXStartUp 

pha 

_MHStartUp 
jsr ErrChk 

pulluord User ID 
oca rtlOOOOQOOQ 

sta NemlC 

.MTStartUp 

; Get direct page space for other tools 



iMemorv needed for direct pages 
toirect page handle deref pointer 



. Start the Tool Locator 

i Result Space for User ID 

. start the Memory Manager 

:Check for errors 

:Get our User ID and save it 

;munge an auxiliary ID... 

;used for Memory Manager handle usage 



-Start the Misc Toolset 



Pha 

pha 

push long « DPSpace 

pushword HemlD 



;Long result space. , - 

; .for returned handle 

iLong value: size of memory block 

;Use the special ID for handle allocatu 
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pushword ISc005 
push long MOOOOOO 
_.NewHandle 
jsr ErrChk 
pul 1 long HndlRef 
ioa CHndlRef] 
sta DPBase 


iPixed, Page-aligned, Locked. UnpurgaDle 
inhere our Dlock resides (KJO/OOOO) 

; Check for errors 

[Get handle of new Dlock 

;Get address of the storage area 

;Save it for GetDP utilities 




Ida »3»Page 
jsr GetDPs 
pha 

pushwora t»oo 80 
pushword MOOaO 
pushword User 1 D 
_ODStartUp 
JSC ErrChk 


lOujckDraw requires 3 direct pages 
;Get address for them,., 
i... and push it 

; Screen Mode tuse S0000 for 320 mode) 
;Pixel Hap Site tuse «0050 for 320 mode) 
;Push our program's ID 
: Start QuickDraw 11 




jar GetDP 
pha 

Pushword 120 
pushword 10 
pushword 11640 
pushword «0 
pushword »200 
pushword User ID 
.EMStartUp 
jsr ErrChk 
pushuora SO 
.SetBackCc-lor 


; Requires a Direct Page 

;Push the DP address 

: Event queue size 

;Hkn X clamp 

:Hax X clamp (.$40 mode" 

;Htn Y clamp 

:Hax y clamp = 200 (oottom of screen) 

;Push program s User ID 

; Start the Event Manager 

iStanoara Dackgrouna color 




Pushword 13 
_SetForeCoior 


;Stanaara foreground color 




pushuora i260 
pushword 195 
_MoveTo 


;X position of message 
;V position of message 
;Move pen to X.Y 




push long *Hament 
_DrawCStrmg 


;Point to a message string 
:Pnnit 'One moment..." 




push long (Tool ist 

_LoadTools 

jar ErrChk 


iPoint to a list of tools 
;Read tools from disk into RAM 




pushword User ID 
JrfindStartUp 
jsr ErrChk 


; Requires User ID 

! Start the Window Manager 




pushword User ID 
jsr GetDP 
pha 

.CtlStartUp 
jsr ErrChk 


Requires User ID.. . 
;. . .and a Direct Page 

:Start the Control Manager 




pushword User ID 
jsr GetDP 
pha 

_MenuStartiUp 
jsr ErrChk 


: Requires User ID. . . 
:.. .and a Direct Page 




_DeskStartUp 
rts 


: Start the Desk Manager 
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PrepDeskTop anop 

push long «0 
.Refresh Desk top 
_lnitCursor 



NxtMenu pha 
pha 

Ida 

as I 

tax 
Ida 
pho 
pho 

pha 

_NewHenu 
pushword HO 
lnsertMenu 



HenuTbl 
A 

MenuTbl.x 



dec 
One 



MenuTBl 
NxtMenu 



pushword il 
_FixAppleMenu 

pha 

^FixMenuBar 

pla 

_DrawHenuBar 
rts 



DoMenu Ida TaskData 

and »»00ff 

asl A 
tax 

jsr <MTable.x> 

pushword *FALSE 
pushword TaskData*2 
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• Prepare Desktop ana Menus • 



• Apple Menu 


About 




About 


rts 






• File 


Menu: 


Quit 




Quit 


dec 
rts 


OF lag 




* 


Do Menu Select 


on 



;Draw entire desktop using default values 



! Result Space <Long> for,., 
i ...the menus handle 
iGet menu count 
tx 2 

;Hake it an index into word values 
;G*t address of menu structure 
:Push program bank twice 
iCPHB pushes only a byte) 
;Push address of menu structure 
:the menu handle is now on the stack 
; Insert menu at left, shifting right 



:Hore menus to install? 
;Yes 



;Put Desk Accessor ies' 3 in Apple Menu 



;Result space 

iCalculate menu Dar s height 

; Discard height for now 

iDisplay the menu oar 



;Does nothing cfor now) 



;User wants to quit tOFlag = Sffff) 



;Get TaskData Item ID numeer 
iDiscard upper 6-bits 
;Double the value 

iDispatch the proper menu item handler 

:We need to unHilite the menu title now 
;Get TaskData Menu number 
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_Hi I iteHenu 
rta 



;Unhi lice menu title 



* Startup/Shutdown Tool List » 



• Shutdown Toolsets 



ShutDownToola 


anop 


i aa 


Toolist 


d3l 


A 


as] 


k 


tax 




Ida 


roolist-2.x 


crap 


i»OO02 


Dne 


Shut! 


pushuora Mem ID 


_Dispose*l l 


pushword User ID 


Ida 


■*0Q02 


Shutl or a 


M0300 


tax 




JSl 


Tooltxw 


oec 


Tool I at 


One 


ShutDownToola 



• 


Ha 


in 


Ha in 


jsr 
jsr 


StartUpTools 
PrepDeskTop 


Scan 


pha 

pushword Hllfl 

push long aEventRec 

JTaafc Master 

Pla 

Deq Scan 




cnp 
bne 


mi 

Scan 




jsr 
bit 

bpl 


DoMenu 
OF lag 
Scan 




jsr 


ShutDownToola 




jxilt 


Oparms 


■ 


Variable 


Storage . 


User ID 
Hem ID 
DPBase 
QFlag 


as 

OS 

da 
dc 


2 
2 
2 

i -FALSE' 



;Get » of toolsets started up 

:x2 

;x2 do create moey over longuoroa) 

,Get toolset ID from list 

; Memory Manager? 

iNo, so shut this down right now 

:Dispose all handles allocated 

:Shui down this program s memory 

iHMShutDown 

;Kake it a shutdown call 

5 Set X to cal I number 

;Shut i t oown I 

rShutdowxi another toolset? 

;Yes 



:Sian toolsets 

;Prepare desktop ana menus 

; Result Space 

: Event Mask 

iPoint to Event Record 

(Get HandleEvent flag 

(If nothing, continue looping 

:A menu event? <*1 i«v]nHenuBar) 
iHope, just keep scanning 

;Do menu item dispatch 

;Time to quit? 

:No, keep scanning for events 

:Shuc down all tools started 

;E*it this program through ProDOS 16 



;Our User ID 

:Memory User ID cmade from User ID) 

:Used by DP butter manager 

;Boo!ean: Quit flag Cslarts out as false) 



Toolist dc 


I ' (Tool stE 


Too 


ist-l>/4" ;Tool count 


dc 


I '1,0* 




1 Tool Locator 


dc 


l'2,0' 




I Memory Manager 


dc 


t'3,0- 




t Misc Tools 


dc 


1-4.0- 




i QuickDraw II 


dc 


l'6,0- 




; Event Manager 


ac 


1-14.0 




; Window Manager 


dc 


116,0' 




: Control Manager 


dc 


1-15,0' 




; Menu Manager 


dc 


■ ■5.0 




; Desk Manager 


ToolstE 


anop 






» Pull Down 


Menu Structures 


• 



MenuToi ac 
dc 
dc 
dc 

HenTDIE anop 



i Menu count 



Menul 



Menu2 



dc 



dc 
dc 



i"(HenTDlE'MenuTbl-l>/2' 
iMenur sApple 

iMenu2' [File 

i'Nenu3' ;E0it 



C'»fiNXMl'.il'0' lAppli 

c --About This Prograra...\N256-,M0 
c-— -\D' .1 1*0' 
c > 



c'» File \N2'.Jl'u" 
C---0uJtvN257*Oq- .ll'O' 
c > 

e» Edit XH3D' . 1 1 

c --Unao\N250v«E*' ,n o- 
B-—Cut\N25I»Xx-,il'0' 
c ■— Copy\N252»Cc-,il'0' 

c'— Paste\N2S3V*Vv'.il'C 

e«\N254'.il'0' 
c > 



;File 



i Edit 



» Menu Item Dispatch Addresses » 



MTabli 



i -About ' 
I'Quit' 



: 256/ About 
;257/0ult 



(Apple Menu* 
(File Menu) 



The Event Record 



EventBec 
EWhat 
EMsg 
EWhen 

EVhere 
EM ods 
teafe Data 

TaskMask 



anop 




da 


2 


03 


4 


as 


4 


as 


1 


da 


2 


ds 


4 


dc 


i4'Sl»ff 



; Event Record used by Taskmaster 

:What 

; Message 

;When 

;Where 

iKodi f lers 

;Task Data 

iTaafc Mask 
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Hi see I laneous Data 



dement dc 



QParms dc 
ac 



c'One Moment...' .il'O' 

14' 0' :ProD03 16 Quit Code parameters 

I'SQOQQ' 



END 



The sample program written in APW machine language will 
create a four-block object file on disk. Of that, one block (512 
bytes) of header information is used for the System Loader. The 
last three blocks contain the actual machine language program. 

Program 6-2. MODEL.C 



MODEL. C 

Sample Desktop Application in APV C (J.Oj 



■ inc 


uae 


ttypes.h; 


• inc 


uae 


«.stdio.h.» 


• inc 


uae 


^ locator .h> 


* include 


<memor y . h > 


# include 


mhisciooI .h> 


•include 


<quickorav.h> 


*inci use 


<event .h> 


• include 


^window. h> 


• inc 


uae 


<menu.h> 


• inc 


ude 


<control .h> 


■ inc 


uae 


<aesK.h> 


• 




Giooal Variables 


WmTaskRe< 


EventRec; 


Word 




Event , 
User ID. 
HeralD. 
QPlag: 


Vera 




ToolistC) - « 

3. 

14. 0. / 

15, 0. 


h 




16, 


char 




*0PBa«; , 


• 


Handle Toolbox Errors 



/* Event Record Structure »/ 

/« Event code «/ 

/* Our User ID •/ 

/» Memory Management ID */ 

/■ Boolean! Quit t lag »/ 



/• Tool count »/ 

/* Window Manager •/ 
/* Menu Manager «/ 
/* Control Manager »/ 



/« Direct Page Base pointer t/ 
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EfTChkC) 

( 

if C_toolErr) SysFailHgr< toolErr, nil>; 
) 



/« Check for error, die i f so */ 



/*- 



* Manage Direct Page Buffers * 
» , 4/ 



char 
Wora 

( 



*GelDPCbytes) 
oytes; 



} 

/•- 



char «0loDP - OPBase: 
DP Base +« bytes; 
return lOldBP); 



Start up Tools 



/* Update case level pointer •< 
/* Return old DPBase pointer «/ 



StartUpToolstJ 
< 

Word GetOPt > i 



/» Force words from Get DP */ 



TLStartUpt >; 

User ID - HMStartUpOt 

MeralD = UserlD i 256; 

HTStartUpO; 

DP&ase = «<NewHandle<0x600L, MemID, 0xe005, ntl>); 
QDStartUp(GetDPe0x3O0). 0x90. OxaO, UserlD): 
EHStartUpCGetDPtOxlOO). 0x14. r 0x260, 0, 0xc8. UserlD); 



SetBackColorCO: 
SetforeColorO); 

Mo.cTuIOaIO-*, OxOO>| 

DrawCString<"One Homent , , ." >; 



/• Show Intro Screen •/ 



ErrChkOs 



ErrChM >; 
ErrChkOs 
ErrChM); 



LoadToolsCToolist >; ErrChkO; /• Load 8. Startup tools »/ 

VuidStarUJp<UserID>s ErrChkO; 

CtlStartUptUserlD, GetDPtCxlQQ)); ErrChkO; 
HenuStartUpCUserlD, GetDPcOxlOO >); ErrChKOi 
DeskStartUpO; 
) 

/»-*— * 

* Prepare Desktop and Menus • 



PrepDeskTopt > 
( 

static char *App I eHenu [ ] =' < 
■>>9\\XN1". 

•--About Thi3 Program... WN2S6" . 

•—WD'. 

">■ 

)! 
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I 



.-»- 



static char «FileKenu()i » C 
'» File WN2". 
•--Quit\\N257«Qfl'. 

); 

siatic char «EaitrtenuIl ■ { 
» Edit WN3D". 
— Unoo\\N25CV»Zz- , 
--Cut\\N251*Xx". 
--Copy\\N2S2»GC'. 
--Paste\\N253V*VV . 
— CI«ar\XN25'C. 



Refresh DeSktOptni I >; 
ImtCursorc >: 

InsertMenutNevMenutEaitHenutQ)), 09 ; 
1 user tllenu « NevMenu < F i I eHenu [01). ) : 
Insert Menu (NevHenuiApp I eKenuIOD , 0) ; 

FixAppleHenui 1) ; 
FixMenuBarO; 
DravMenuBart )| 



/« Display Desktop »/ 
/» Show mouse cursor »/ 



/• install menus •/ 



■-'« Display menu bar »/ 



» Apple Menu: About 
* .......... 

About* > 
{ 



I 



/i Dobb nothing <for now) */ 



* Do Menu 


Selection » 


DoMenuo 
( 

SuitChCEventRec.wnTaskData) ( 
case 256: About! 
break) 
case 257: OF lag - TRUE; 

break : 
i 



/» Apple nenu: About */■ 

/■ Pile tlenu; Quit •/ 



Hj 1 1 terlenuc FALSE. EventRec.wmTaskData»l6> i 



Shutdown Toolsets 
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ShuiDownToolsO 

t 

DeskShutDownCJi 

HenuShutDovmC 3 ; 

CtlShutDovnUs 

ihndShutDownt): 

EHShutOounOi 

QDShutDownO; 

MTShutDovnOi 

DisposeAIKrlemlD): 

WIShiitDovntUserlOJi 

TLShutDovnOi 

> 

/, 



Ham 



maim ) 
i 



StartUpToolfli >; 
PrepDeskTopf i; 



OF lag = FALSE! 
EventRecwmTaskMask 



/* Start toolsets •/ 

/* Prepare desktop and menus »/ 



OxOOOOlfff s 

/■» Wait for a menu event •/ 



while <!0Flag> ( 
do ( 

Event ■ TaskHasterCOxf Iff . lEventRec); 
J While <! Event); 

if cEvent ■» wtnMenuBar) DoMenuO: 
) 



Shut Down Too I sC >; 
exittO)! 



/■ Shutdown all tools started «/ 



The sample program written in APW C compiles into a 16- 
block object file. However, a compiled C program containing no in- 
structions at all produces a 12-block file. This means that, like the 
assembly program, about 4 blocks contain the actual code, while 
the other 12 consist mostly of overhead from the standard C library 
and System Loader. 

Program 6-3. MODEL.PAS 



HODEL.PAS « 

Sample Desktop Application in TNL Pascal tvi.OD • 
--- — * J 



PROGRAM MOW IP: 

USES ODIntF. 
GSIncF, 
HiSCTools: 
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i * . 

• Glooal Variables • 

• 1 j 

VAR EvefttRec: EventRecord; < Taskmaster Structure ) 

Event: Integer: < Event coo* 3 

UserlD: Integer: < Our User ID ) 

MemJD: Integer: ( Memory allocation ID 3 

DPBase: Integer: < Direct Page ease pointer ) 

QFlag: Boolean: \ Boolean; Quit (lag > 

AppleHenu: String; < Pull down menu strings ) 
FileHenu: Strings 
EdltHenu: String; 

( . .... » 

« Hanoi* Tooloox Errors » 
. ) 

PROCEDURE ErrChk: ( Check for error, die il so ) 

BEGIN 

IF IsToolError THEN 

SysFai IMgrtToolErrorNum. Tool error -> >'>; 
END; 

( a---. —- ■ 

« Manage Direct Page Buffers * 
»---■ - » J 

FUNCTION GetDPtDytes: Integers integer: 

BEGIN 

GetDP := DPBase; I Return current DPBase ) 

DPBase : = DPBase » bytes: < Update c-ase level pointer ) 

END: 

( « — — - - * 

* Start Up Tools * 

• - • ) 

PROCEDURE StartUpToolsr 
VAR 

Toolist: ToolTaDle; ( Disk-based tool list > 

Height! Integer: ( Henu car heigth CunusedJ > 

BEGIN 

Too I i st . NumToo I s :» 3; ( Tool count I 

Tool ist. Tools! n.TSNum i- Ml ( Window Hanager ) 

Tool ist, Tools! 1 1 .HinVersion :■ 0; 

Tooli3t.Toolsl21.TSNum := 15; ( Henu Menaeer > 

Tool i3t.Tool3l2] .HinVersion :» 0; 

Toohst.ToolslSJ.TSNum := 16; < Control Manager > 

Tool ist.ToolsUl. HinVersion :■ 0; 

T (Startup: 

UserlD : = HMStartUp; ErrChk: 

HeratD w UserlD * 256; 

HTStartUpi 

DPBase : = LoWord(NewHandle<3600. NemlD, «c005. Ptrt0»r>; ErrChk: 

ODStartUp<GetDPt»300«. »80 , tad, UserlD); ErrChk: 

EriStartUp<GetDP«»10O>. »H. 0, S280. SO. 3cB, UserlD); ErrChk: 



n 



SetBack Colored); 
SetForeColor<3>: 
MoweTol»104. 3553: 
DrawStrmgC'One Moment... J: 

LoadTool3<Toolist); ErrChk; 



Show Intro Screen ) 



i Loaa & Startup tools i 



END; 



VinOSlartUptuSerlD): ErrChk; 

CtlStartUpCUserlD, GetDP(SlOO) 3; ErrChk: 

MenuStartUptUserlD, GetDP<»100)) ; ErrChk; 
DeskStartup; 



• Prepare Desktop ana Henus « 



PROCEDURE PrepDWSkTop; 
VAR 

Height: Integer; 

BEGIN 

AppleHenu :* CONCATt -»a\XNl\0" , 

--About Th is Program. . .\N256vO , 
'— \0\0'. 
->'3: 



FileHenu := CONCATC 



EdltHenu : = CONCATc 



END; 



» File KN2\0'. 

— Oult\M2S?»Qq\0'. 

> ): 

>> tan \N3D\Q . 
— Unoo>N250°«VZz\n- 
--Cut\N25l»Xx\0' . 

-Copv^N252«Cc\0'. 
--Paste\N253V»Vv\0' 
— Clear\N25«\Q'. 

> ); 



RefreshtNilJ; 

im tcursor; 

InsertHenuCNeuflenuiSEdiiHenuim, 0>; 
InsertHenuCNeuHenutftFi leMenul 11), Q>: 
InsertMenutNevMenuOAppleHenutll). 0); 

FixAppieHenu< l>; 
Height := FixHenuBar; 
DravflenuBar; 



( Displ ay Desktop ) 
( Show mouse cursor J 



( Install menus > 



{ D isp I ay menu bar > 



C ■ 

• Apple Henu: About 



PROCEDURE Aoout; 
BEGIN 

( Does nothing cfor now? ) 
END; 
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Do Menu Selection 



-* ) 



PROCEDURE DoWenu: 
BEGIN 

CASE LoWord<EventRec.TaskD«ta> OF 

256: About; 

257: QFlag f- TRUE; 

END: 



( Apple Menu: Aoout ) 
I Fl te Henu: Ouit > 



END: 
( •- 



Hi liteNenutFALSE, HiVord(EventPec.TaskData) >: 



Shutdown Toolsets 



PROCEDURE ShutDownTools; 
BEGIN 

DeskShutDown; 

MenuStmtDoun; 

CtlShutOcvn: 

Wi noShutDoun: 

EHShutDoun: 

ODShutDowfi; 

HTShutDown: 

DisposeAl UNemiD); 

HHShutDowrullserlD); 

TLShutDown: 
END: 



t *- 



Ham 



BEGIN 

StartUpTooIsi 

Prep DeskTop; 

OF 1 49 t- FALSE: 
EventRec.Taskjlask 



i Start toolsets J 

< Prepare desktop and menus ) 



sOOOQlfff ; 

t Wilt tor a menu event ) 



REPEAT 

REPEAT 

Event := TaMlMterOffff. EventRec); 

UNTIL Event <> 0: 

IF Event - vlnflenuBar THEN DoHenu; 
UNTIL QFlag: 



ShutDownTools 



END. 



C Shutdown all tools started ) 



Surprisingly, the TML Pascal example compiles into an eight- 
block runtime file, half the size of the C program. 

These sample programs are written so they can be compared 
to each other easily. This does not necessarily mean that they have 
been written in the best format for the language used. For example, 
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since Pascal is relatively inflexible, the machine language and C 
programs have a very Pascal-like "bottom-up" format in order to 
keep the functions parallel. 

Since all three programs make extensive use of routines in 
ROM, they run at roughly the same speed. They should be studied 
carefully and used as models for more complex DeskTop 
applications. 

If you diligently typed in one of the model program listings, 
successfully compiled it, and were mildly impressed with the re- 
sults, don't give up now. These model programs were intentionally 
created as skeletons. They form the basic parts of all DeskTop 
applications. 

The chapters that follow discuss key portions of the sample 
programs in greater detail. They show how to add more pull-down 
menus, custom windows, dialog and alert boxes, and special dialog 
controls. With a little imagination and this book at your side, 
you're on your way toward a rewarding programming experience. 
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Memory 
Management 

Many Apple IIGS programmers 
have their roots in earlier Apple 
II computers. Perhaps you're one 
of them. If so, you are well 
aware of the anarchy that pre- 
vailed in the 64K RAM Apple II. 
Apple had cleaned up the neigh- 
borhood when the memory- 
management system was created 
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for the Apple lies. It was something that had to be done. 

This chapter is about memory management. It may sound like 
a dry subject, but it really isn't. In fact, compared to the jungle-gym 
memory management of earlier Apple II computers, the designers 
of the Apple IlGS have blessed the programmer with a memory- 
management system that's reliable, easy to manage, and easy to 
program. 

New Rules 

Imagine an Apple II with eight megabytes of RAM (128 times more 
memory than a 64K Apple II) and no sensible way of managing it 
all. Programs would overwrite each other, and there would be no 
way to locate lost data, which might be intact but as irretrievable as 
a needle in a hayfield. Before long, memory would be as packed 
with as much useless information as a poorly managed bookstore. 
A horrific thought. But thanks to the Memory Manager built into 
the IIGS, programs can coexist in peace for the first time in Apple II 
history. 

This is a radical departure from the programming environment 
of older Apple Us. If you're moving up to an Apple IIGS from a He 
(or Ik or 11 + ), you're in for a surprise. Gone are the days when a 
program grabbed a hunk of memory for its own purposes. 

With the Memory Manager in charge, memory blocks are allo- 
cated to applications that request them. Memory blocks can be any 
size, and they can contain any type of information. But a program 
must specifically ask for a block of memory or risk the complete 
destruction of any space it arbitrarily claims. 

A memory block may be located anywhere in RAM. It is very 
rare for a program to ask for a block of memory that always resides 
at a fixed address in the machine. In fact, it's considered sloppy 
programming if your application cannot deal with memory blocks 
that move around in the Apple llGS. The memory blocks that the 
Memory Manager hands out will not always live at the same ad- 
dress in the computer, and there's a good reason for this. 

As more and more applications reside inside the computer at 
the same time, their impact on memory usage will vary. Some pro- 
grams might require a small portion of RAM for temporary usage 
and then throw it away when it's no longer needed. Other pro- 
grams might require memory blocks that could be considered per- 
manently reserved. And still other programs may require great 
amounts of memory. Managing that memory without the assistance 
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of the Memory Manager would be a big headache. 

So, imagine having hundreds of small memory blocks scattered 
throughout your computer's memory. Then imagine that your 
application needs a large, contiguous piece of RAM, but an unused 
area of memory that size doesn't exist. If you couldn't move the 
smaller blocks, rearranging them to make room for the one large 
block, the program would crash. With this kind of demand on 
RAM, things can get messy fast if memory blocks are not allowed 
to be moved. 

Figure 7-1. Memory Blocks Distributed All Over Memory in a Random 
Dispersal 



Fixed & Locked Block 
Purgeable Block 




_^L 



Fixed & Locked Block 

Purgeablc Block 



Figure 7-2. Memory Blocks After Reorganization by the Memory 
Manager 



Fixed & Locked Block 




Fixed & Locked Block 
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Fortunately, part of the Memory Manager's job is reorganizing 
memory blocks. It shuffles movable blocks around in an efficient 
and resourceful manner. This is done by removing blocks that are 
flagged as unused and then sliding blocks around in order to fill 
any gaps. The effect is that the landscape inside the computer is 
kept neat and orderly. 

Don't let this worry you. It's possible for an application to re- 
quest a block of memory that will reside at a fixed location, if you 
want it. However, the odds of the Memory Manager denying your 
request are higher because that space might already be reserved by 
another program. 

Of course, if blocks of memory can be allowed to move about, 
seemingly at will, there must be a way to keep track of where 
they are. 

Getting a Handle on Memory Blocks 

Since a memory block can move around inside the computer, it is 
referenced by a handle. You'll see handles used with anything that 
moves about or that doesn't have a specific, given, or constant lo- 
cation, such as memory blocks, records, structures, and so on. Han- 
dles are simply long-word pointers to an address stored in memory, 
and they're used frequently in programming the Apple IlGS. 

In the case of memory blocks, a handle points to a location in 
memory that contains a list of items. This list is also referred to as 
the memory-block record. For example, the first item in the list is a 
long-word address containing the actual location of the memory 
block's data in memory. The other items will be discussed later in 
this chapter. 

Recall that a memory handle is a pointer. It points to a list of 
items. The first item in the list is an address which points to the 
location in memory where the memory block lives. This can be 
confusing. 

If the memory block is moved, the only thing that changes is 
the address in the memory-block record. The handle still points to 
the same structure. Your program won't need to adjust anything if 
it's working with the handle correctly to begin with. 

Suppose that you have a friend whose name is Kitty. On a 
page in your address book, you have recorded her name, address, 
birth date, and dozens of other pieces of information about her. 

Kitty has a problem: She is always being evicted from her 
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apartment. Whatever other information you have about Kitty is al- 
ways the same: She never changes her hair color, her birth date, 
her parents, or her telephone number, Only her address. The line 
in your address book where her address is written is the only thing 
you need to change in order to keep up to date on Kitty. That 
much-erased line in your address book is analogous to the memory- 
block record. 

Starting the Memory Manager 

Just as its name implies, the Memory Manager is responsible for 
keeping the computer's RAM neatly organized. This is done by tag- 
ging with an identification number each chunk of memory owned 
by an application. Whenever the Memory Manager is called upon 
for moving, purging, or manipulating a block of memory, your pro- 
gram must identify its piece of RAM. This is done by passing along 
an identification value when calling the Memory Manager. 

Even the space that your program occupies is branded with its 
own identification number. The ID of your program is obtained 
when the Memory Manager is started. 

The following examples show how a program obtains its own 
ID. This is typically one of the first calls an application should 
make. 

In machine language: 



pba 

-MMStartUp 

pla 

ata 



UserlD 



;word result spaoe 
; start the Memory Manager 
;pull Master Dser ID 
;and save It 



In Pascal: 
UsBrlD : - MMStartUp; 

In C: 

UserlD = MMStartUp( ); 

These samples demonstrate the steps involved in starting the 
Memory Manager in 65816 machine language, Pascal, and C. The 
UserlD, declared as a 16-bit unsigned integer, is a unique identifier 
that belongs to your application. It should always be saved for 

later use. 
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User ID Numbers 

The ID value returned by MMStartUp is your program's master 
User ID. It references the space your application takes up in mem- 
ory. The User ID is used when shutting down both your program 
and the Memory Manager. 

The ID value consists of 16 bits, grouped into three parts, or 
fields. Bit positions within the word value represent the different 
fields: 



Field: 

User ID: 
Bit: 



Type ID 



Aux ID 



Main ID 



15 14 13 12 11 10 9 



7 6 5 4 3 2 10 



The Type ID field occupies bits 12-15, Type ID identifies the 
class of software the User ID belongs to. It may be one of 1 1 
values: 

Value Class of Software 

$0 Memory Manager 

$1 Application 

$2 Control program 

$3 ProDOS 

$4 Tool set 

$5 Desk accessory 

$6 Runtime libraries 

$7 System Loader 

$8 Firmware 

$9 Tool Locator 

$A Setup file 
$B-$F Undefined 

The Auxiliary ID field occupies bits 8-11. This field is initially 
set to 0, but you can manipulate it to create up to 16 different sub- 
ID's for your program. For example, to set bit 8 (the least signifi- 
cant bit of the Aux ID field), the following can be done. 

In machine language: 



Ida UserlD 

ora *%100000000 

ata MemlD 

In Pascal: 



;Get the UBBr ID . . . 

;. . . and set bit 8 
;Save tbe new ID 



MemlD : = User-ID + 256; 



100 






Memory Management 



Chapter 7 



In C: 

MemlD = UserlD I 288; 

This should be done before an application requests memory 
from the Memory Manager, An auxiliary ID value is used rather 
than the program's User ID. The memory allocated can then be cat- 
egorized by your program as an example of using this field. Other- 
wise, if you don't want to get that detailed, you can ignore the Aux 
ID field. But it's there if you need it. 

The Main ID field occupies the lower eight bits of the User ID 
returned from the Memory Manager. This is a unique number as- 
signed to your program's User ID by the Memory Manager. Your 
User ID is what makes your program special. It makes your pro- 
gram different from any others that are running in the machine. 
The lower eight bits of your User ID should never be altered. To 
do so would be like changing your own fingerprints. 

Asking for Memory 

When a ProDOS 16 application is launched, it is given its own 64K 
bank of memory to live in. It also has its own direct page and 
stack. If the program requires memory outside its code space for 
storage, it must call the Memory Manager's NewHandle function to 
request a block of memory. 

This 65816 code segment calls the NewHandle function in or- 
der to request a 256-byte buffer in bank $00 of the computer: 

pha .long word result space 

push size of requested block (one page) 
push a Memory ID (made from the User ID) 
Attribute bits (discussed later) 
Location of block in memory (not used) 

;oall the NewHandle function 

This call requires four input parameters (and result space when 
called from machine language) in order to work: 

Value Parameter Description 

Long word Size of the memory block needed 

Word An ID value to assign to this block 

Word Attributes (discussed later) 

Long word Location of the block (if applicable) 



pha 




pushlong 


•4100 


pushword 


Mem ID 


push word 


IC00B 


pu&hlong *0 




_NewHandte 





Value Parameter Description 

Size The size of a memory block can be anything from zero bytes 

to whatever free memory space there is left in the machine. 

ID As described earlier in this chapter, each memory block allo- 

cated to a program must be identified by an ID number, 

Attributes The attributes of a memory block determine certain charac- 
teristics about it (where it can reside, if it can be moved, and 
so on). Attributes are very important. They will be discussed 

in detail later in this chapter. 
Location If the memory is to reside at a fixed location in memory, this 

long-word value determines the address requested. 

NewHandle doesn't return a pointer to the location of the re- 
quested block of memory. Rather, it returns a handle to that block. 
The handle will be waiting to be pulled from the stack after this 
call is made from machine language — which is an important detail 
to remember. 

The handle references the memory-block structure just allo- 
cated. Within that structure is the actual address of the memory 
block. That address is obtained in the following manner: 

;get low -order word of the handle 
.get high-order word of the handle 
.build a long pointer at location *00 



pla 




Plx 




sta 





stz 


2 


sta 


TheHandle 


ati 


TheHandle + 2 



;and save the address for later 
:(mlght be used for disposal) 

The handle has been pulled from the stack and stored in four 
bytes from memory locations $00-$03. A copy has also been stored 
in TheHandle, a four-byte storage area within the program. By 
putting the value returned by NewHandle at location $00, a long- 
address pointer is created. This can be referenced indirectly in or- 
der to fetch values in the memory block's record. 



Ida 


[0] 


.get 16-blt addrese of the memory block 


eta 


BlockAddr 


;. . . and save It 


Idy 


*2 


: Index passed the first word . , . 


Ida 


[Q].y 


;. . . then get the bank of the memory block 


sta 


BlockAddr + 2 


;and save It 



The address contained in the four-byte storage area named 
BlockAddr is the location of the 256-byte page of memory that was 
allocated with NewHandle. In fact, due to the location and 
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attributes of this memory block, it could be used as direct-page 
space by a tool set. 

Since direct pages reside in bank $00 only, the high word of 
the address need not be retrieved from the memory handle record. 
The most significant word of the address is assumed to be 0. 
Example: 



Ida [0] 

sta DPageAddr 



:get the direct page addreea 
;. , . and eave It 



DPageAddr would simply be a two-byte storage area in your 
program. 

Using NewHandle in Pascal and C is far easier. In Pascal, the 
following is used to obtain memory for direct-page space: 

TheHandla := NswHandleCJlOO. MamlD. $0005. Ptr(O)); 
DPageAddr : = LoWord(TheHand]e"); 

These statements are identical in operation to the machine lan- 
guage example listed earlier. The four parameters in the above ex- 
ample that constitute the NewHandle requirements are block size 
requested ($100), an ID (MemlD), attributes ($C005), and the 
block's address (0). 

The following illustrates grabbing a memory handle using C: 

TheHacdle - NewHandle(0xl00L. MemlD. OxCOOS. nil); 
DPageAddr = (tot) '(TheHandle); 

These statements are identical to the machine language and 
Pascal examples. 

The Memory-Block Record 

The memory-block record is one of those things you really don't 
need to know about in order to program the Apple IlGS. The struc- 
ture and manipulation of memory handle records is not part of the 
regular programmer's repertoire. In fact, the only time you would 
examine a record is to locate a memory block's true location in 
memory. And the purpose of having a Memory Manager is to 
avoid that. 

Each block of memory allocated by the Memory Manager has 
a corresponding record. {Recall that the record is what the handle 
points to.) The structure of this record consists of six fields that 
give the memory block's address in memory and provide additional 
information about the block. 
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The long-word value (handle) returned by NewHandle is the 
address in memory where the memory block's record is stored. 
This record is 20 bytes long, and it contains the following 
information: 

Size Contents 

Long word Address of the block 

Word Attributes 

Word Owner's User ID 

Long word Size of the block 

Long word Pointer to the next handle record 

Long word Pointer to the previous handle record 

The first four fields are copies of the parameters used when 
the NewHandle call was first made. See the previous section for 
details. 

The tast two items require further explanation. 

In order to keep track of these handle records, the Memory 
Manager uses a set of next and previous record pointers to create a 
linked list. The first long-word pointer points to the next 20-byte 
memory handle record, while the second pointer points to the pre- 
vious record. This allows handle records to reside in any order 
throughout the computer's memory, yet they can be referenced in 
order due to their link fields. 

Block Attributes 

When NewHandle is used to allocate a block of memory, you must 
decide how that block should be treated by the Memory Manager. 
For example, should the block be allowed to move around? Does it 
have to be aligned on a 256-byte page boundary (which speeds up 
some processes)? Can it reside in special memory banks? You'll 
have to consider these points, and more, when allocating a new 
handle. Time to think. 

Block attributes are assigned by the programmer before the 
MewHandle function is called. The attributes parameter is a word 
value and consists of 16 bits of information: 

Bit Meaning If Set (Made Equal to 1) 

Block must reside in a particular memory bank 

1 Block must reside at a particular address 

2 Block must be page-aligned 

3 Block can reside in special memory banks 

4 Block cannot cross a bank boundary 
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Bit Meaning If Set (Made Equal to l ) 

5 Reserved 

6 Reserved 

7 Reserved 

8 Purge level (low bit) 

9 Purge level (high bit) 

10 Not used (0) 

1 1 Not used (0) 

12 Not used (0) 

13 Not used (0) 

14 Block is fixed (cannot move) 

15 Block is locked (fixed and unpurgeable) 

Each bit position represents a specific attribute describing the 
memory block to be allocated. Setting a bit asserts that attribute. 

Bit Specifies whether the block should reside in a particular 

bank of memory in the computer. For example, if your 
application required a memory block that must reside in 
bank $05. you would set this bit. 

Bit 1 Specifies that the block must live at a particular address in 

memory. Memory blocks that reside at fixed addresses 
should also have bit 14 set (which means they cannot be 
moved). 

Bit 2 Causes the block of memory to reside on a page bound- 

ary. A page is 256, or $100, bytes of RAM. The first page 
boundary is at location $0000 in a bank. The next page is 
at location $0100. The next page would be at location 
$0200, fallowed by $0300, and so on, all the way up to 
$FF00, the last page boundary in a bank. 

Bit 3 Determines if a block can reside in the special memory 

banks $00, $01, and $E0 and in bank $E1. These banks 
are used by the Mega II (Apple lie-emulation) mode of 
the Apple IlG5 when an application runs under the 8-bit 
version of ProDOS. If you create a memory-resident appli- 
cation for the Apple Ilc.5, such as a desk accessory, it can- 
not reside in special memory. In native (16-bit) mode, 
bank $00 is used mainly by DeskTop applications for di- 
rect-page space. 

Bit 4 Tells the Memory Manager if the block can cross from one 

bank to the next in the computer. For example, a $2000- 
byte block, living at location $03FE00 could cross over 
into bank $04 if bit 4 was not set. 
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Bits 5-7 Reserved and should not be set. 

Bits 8 and 9 Classify the purge level of a memory block. Because there 

are just two bits, four unique settings can be assigned 

(2X2 = 4): 

Value Meaning 

The block cannot be purged 

1 Very low purge level 

2 Moderate purge level 

3 Very susceptible to purging 

Blocks are purged when the Memory Manager is called to compact 
memory and clean house. As you can see, blocks with the highest 
nonzero purge levels are purged first 

Bits 10-13 No use at this time. 

Bit 14 Fixes a block in memory so it cannot be moved. 

Bit 15 Used to lock a memory block. Locking causes the block to 

become immovable and unable to be purged, regardless of 

the settings of bits 8, 9, and 14. 
The Memory Manager tool set provides functions for changing 
the attributes of a block after it has been allocated with 
NewHandle. They are the following: 

Function Description 

HLock Locks a memory block referenced by its handle 

HLockAll Locks all memory blocks referenced by a User ID 

HUnLock Unlocks a memory block referenced by its handle 

HUnLockAH Unlocks all memory blocks with a certain User ID 

SetPurge Sets the purge level of a block referenced by handle 

SetPurgeAll Sets the purge level for all blocks with the same ID 

The summary at the end of this chapter fists the parameters for 
these functions. Note that COMPUTED Mastering the Apple llGS 
Toolbox provides parameter descriptions for the entire Apple lies 
Toolbox, 

Removing Memory 

Memory is removed by eliminating memory handles (the same 
handles that were obtained by the NewHandle function). When a 
handle is removed, the Memory Manager is allowed to make avail- 
able the space that its memory block took up in the computer 

Any handles allocated by your application should be removed 
as soon as they are no longer needed. This will make the memory 
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they occupy free for use by other applications. Handles can be re- 
moved in a number of ways using the Memory Manager tool set. 

The most straightforward method of removing a memory block 
is to use the DisposeHandle function. Your application pushes the 
handle's value onto the stack and then DisposeHandle is called. 
The memory block and its allocated handle are removed from the 
system instantly. 

In machine language: 



puBhlong TheHandle 
—DisposeHandle 



;push th.8 handle on the stack 
;and now dispose of It 



The same example in C or Pascal: 

DleposeHandleCTtieHandJe); 

If you have allocated multiple handles with a single identifica- 
tion value, your application can take a shortcut by using the 
DisposeAll function. DisposeAll will remove all handles associated 
with a particular ID number, For example, in C or Pascal: 

DIspOBeAllCMemlD); 

Your programs should never call DisposeAll with the master 
User ID returned by MMStartUp. This would cause the memory 
space that a program occupies to be freed, which might result in a 
system crash. 

Another approach to freeing a block is to set its purge level to 
the highest setting (3). This would cause the Memory Manager to 
dispose of your block the next time it was called to compact mem- 
ory (CompactMem). Note, however, that the handle remains allo- 
cated and will have to be removed eventually. 

When a handle is purged, the block allocated to this handle is 
freed, but the handle is kept alive. The address of the block in the 
memory block record is set to $0000000 (a long word of 0). This 
tells the Memory Manager that the handle is valid, but does not 
have a block allocated to it. This would allow you to reallocate 
(ReAllocHandle) a memory block at a later time without having to 
use NewHandle to create a brand new one. It is understood that if 
purging does not dispose of the handle, your application will still 
need to do so before quitting. 
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Chapter Summary 

The following Toolbox functions were discussed in this chapter. 
Also included are a few of the popular Memory Manager functions. 

Function: $0202 

Name: MMStartUp 

Starts the Memory Manager 
Push: Result Space (W) 
Pull: UserlD(W) 
Errors: $0207 
Comments: One of the first calls made by an application. 

Function: S0302 

Name: MM5hutDown 

Shuts down the Memory Manager 

Push: UserlD (W) 

Pull: nothing 

Errors: none 

Comments: Make this call when your application is finished. 

Function: $0902 

Name: NewHandle 

Makes a block of memory available to your program 
Push: Result Space (L); Block Size (L); UserlD (W): 

Attributes (W); Address of Block (L) 
Pull: Block's Handle (L) 
Errors: $0201, $0204, $0207 

Function: S0A02 

Name: ReAllocHandle 

Reallocates a purged block with new parameters 
Push: Block Size (L); UserlD (W); Attributes (W); 

Address of Block (L); Old Block's Handle (L) 
Pull: nothing 
Errors: $0201. $0203, $0204, $0206, $0207 

Function: S0B02 

Name: RestoreHandle 

Reallocates a purged block using original parameters 

Push: Old Block's Handle (L) 
Pull: nothing 
Errors: $0201, $0203, $0206, $0208 
Comments: Uses same parameters of original block (unlike function $0A 
which allows the parameters to be reset). 
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Function: $1002 

Name: DisposeHandle 

Deallocates a block and releases its memory 
Push: Block's Handle (L) 
Pull: nothing 
Errors: $0206 
Comments: The block is deleted regardless of its locked status or purge 
level. 

Function: $1102 

Name: DisposeAll 

Releases all blocks associated with a UserlD 

Push: UserlD (W) 

Pull: nothing 

Errors: $0207 

Comments: Ruthless. 

Function: $1202 

Name: PurgeHandle 

Purges a block of memory 
Push: Block's Handle (L) 
Pull: nothing 
Errors: $0204, $0205, $0206 
Comments: The block must be purgeable and unlocked. The block's han- 
dle is not deallocated by this call. 

Function: $1302 

Name: PurgeAU 

Purges all blocks associated with a UserlD 

Push: UserlD (W) 

Pull: nothing 

Errors: $0204, $0205, $0207 

Comments: The blocks must all be purgeable and unlocked. 

Function: S1B02 
Name: FreeMem 

Returns memory available for programs 
Push: Result Space (L) 
Pull: Integer Value (L) 
Errors: none 
Comments: Returns the total number of bytes in memory, not counting 
ramdisks or other allocated blocks. 
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Function: $1C02 
Name: MaxBlock 

Returns memory available to programs 
Push: Result Space (L) 
Pull: Integer Value (L) 
Errors: none 
Comments: Returns the largest free block in memory. 

Function: $1D02 
Name: TotalMem 

Returns total RAM in the System 
Push: Result Space (L) 
Pull: Integer Value (L) 
Errors: none 
Comments: Returns all RAM in your Apple IlGS, including the basic 
256K, any ramdisks, and so on. 

Function: $1F02 

Name: CompactMem 

Compacts memory 
Push: nothing 
Pull: nothing 
Errors: none 
Comments: Performs memory garbage collection, purging purgeable 
blocks and reorganizing memory. Don't do this during an 
interrupt. 

Function: $2002 
Name: HLock 

Locks and sets a specific handle to a purge level of 

Push; Handle (L) 
Pull: nothing 
Errors: $0206 

Function: $2102 
Name: HLock All 

Locks and sets all handles associated with a specific UserlD 

to a purge level of 0, 

Pull: nothing 
Errors: $0207 



Function: 


$2202 


Name: 


HUnLock 




Unlocks a block of memory 


Push: 


Handle (L) 


Pull: 


nothing 


Errors: 


$0206 
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Function: $2302 

Name: HUnLockAll 

Unlocks ail blocks of memory associated with a specific 
UserlD 
Push: UserlD (W) 
Pull: nothing 
Errors: $0207 

Function: $2402 

Name: SetPurge 

Sets the purge level of a given block 

Push: New Purge Level (W); Handle (L) 

Pull: nothing 

Errors: $0206 

Comments: Only the lower two bits of the word pushed are significant. 

Function: $2502 

Name: SetPurgeAll 

Sets the purge level for all blocks associated with a given 
UserlD 
Push: New Purge Level (W); UserlD (W) 
Pull: nothing 
Errors: $0207 

Function: $2B02 
Name: BlockMove 

Copies a block of memory from one address to another 
Push: Source Address (L); Destination Address (L); Length (L) 
Pull: nothing 
Errors: none 

Memory Manager Tool Set Error Codes 

$0201 Unable to allocate block 

$0202 Illegal operation on an empty handle 

$0203 Empty handle expected for this operation 

$0204 Illegal operation on a locked or immovable block 

$0205 Attempt to purge an unpurgeable block 

$0206 Invalid handle given 

$0207 Invalid User ID given 

$0208 Operation illegal on block-specified attributes 
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Pull-Down 
Menus 



In menu-driven programs not 
too many years ago, the com- 
puter's monochrome screen 
would clear and a long list of 
menu items, usually num- 
bered, marched down the 
display: 
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MAIN MENU OPTIONS: 

1. GO TO MENU 2 

2. GO TO MENU 3, SUB MENU C 

3. GO TO MENU 8 AND STAY THERE 

4. DO MAIN MENU OPTION 7 

6. PHBTBND TO GO TO MBNU 7 BUT GO TO MENU 8 INSTEAD 

6. GIVE ME THE BREAKFAST MENU 

7. DO MAIN MENU OPTION 4 

8. JUST GET ME THE CHECK 
ENTER YOUR SELECTION (1-8): 

Pressing a number would erase the old menu and would likely 
unravel yet another screenful of menu items. Somenmesthjs would 
go on through several levels, before anything could get done. Mo- 
bility in this environment was like jogging blmdfolded-w,th 

ShaC Wifh l a 8 De S kTop environment however, the user can see all the 
possible menus at once. Their titles are P? 5 ^ ^^"^^ 
across the top of the screen. Navigatmg through these menu re 
quires little Instruction. They are intuitive and are becoming com- 
monplace in the computer world. Just about everyone has had 
exposure to them. 

The Two Managers 

Programmers who have written interactive software know that 
whTlife is made easier for the user, it usually means the oppose 
for the programmer. Creating user-friendly software requ. res .hard 
work. While this is generally true for applic. tons it ^ <£™ n " 
ments, things couldn't be sweeter for the Apple lies programmer. 
All the credit goes to the Menu and Window Managers. 

As its name implies, the Menu Manager is responsible for 
maintaining the lists of numerous commands and fum : ions a pro- 
gram may contain. It takes care of shuffling menus around, draw- 
ing them on the screen, and interacting with the user while 
selections are made with the mouse or keyboard. 

What does the Window Manager have to do with menus? A 
vital part of the Window Manager is the TaskMaster. The purpose 
of the TaskMaster is to watch for menu events that occur on the 
DeskTop and to handle them appropriately. It relieves the , pw- 
grammer of those bothersome details. However, if an , applicat on 
fequJres custom even, handling, the TaskMaster can be bypassed 
altogether. 
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Organizing Menu Items 

Organization of functions and subroutines is an essential step in 
creating any new program. The same applies to creating pull-down 
menu items. For example, a coffee-shop menu is grouped into sec- 
tions such as Eggs, Pancakes, Waffles, and Side Orders. This makes 
it easier for the diner to locate a particular item. 

In a DeskTop program, the Main Menu of yesteryear's applica- 
tion is replaced by the System Menu Bar at the top of the screen, 
as shown in Figure 8-1. 

Figure 8-1. Breakfast Menu Bar 



Eggs 



Pancakes 



Waffles 



Side Orders 



Within each menu are menu items. For example, the third 
menu, Waffles, might include four items, shown in Figure 8-2. 

Figure 8-2. Waffle Menu 



Waffles 



Apple 

Belgian 

Pecan 

Strawberry 

For the user's sake, items in a pull-down menu should be re- 
lated to the title of the menu. This falls into the department of Ap- 
ple's Human Interface Guidelines (see Appendix A). The guidelines 
were created to help the programmer decide where certain com- 
mands should go, how they should be named, and so on. 

As an example, commands that open and close files, save 
changes to disk, create new files, and interact with the printer, are 
found in the File menu on the System Menu Bar. The command to 
quit a program is also in the File menu. Practically all DeskTop pro- 
grams have a File menu so long as a means exists for quitting the 
application. 

Once an application's commands are organized into menus, 
the programmer must decide which, if any, should have keyboard 
equivalents. Keyboard equivalents are awarded to commands used 
most often. Applications relying heavily on keyboard input, such as 
word processors, ought to provide the user with as many key 
equivalents as possible. On the other hand, people tend to make 



115 



Chapter 8 



menu selections using the mouse while working with drawing or 
painting programs, which makes it less important that graphics 
program menu items have keyboard-equivalent commands. 

According to the Human Interface Guidelines, created by Ap- 
ple's Bruce Tognazzini (lovingly known as 'Saint" Tognazzini), 
some keyboard command characters should be reserved for certain 
functions in order to maintain consistency from one DeskTop appli- 
cation to the next 

Table 8-1. Command Key Equivalents 

Key Command 

C Copy 

O Open 

Q Quit 

S Save 

V Paste 

X Cut 

Z Undo 

The letters listed in Table 8-1 are commonly reserved for the 

listed functions. 

Keyboard equivalents are shown to the right of a menu item, 
preceded by the Open Apple symbol. On the Macintosh, they are 
preceded by the clover-leaf (Command key) symbol. 

The placement of items on the menu bar is also discussed in 
the Human Interface Guidelines. The menus are positioned on the 
menu bar starting with the Apple menu (also called the New Desk 
Accessory menu) at the left side. Following that comes the File 
menu. And if the application manipulates text or graphics, usually 
an Edit menu follows. Consult Appendix A for other reserved 
menu titles suggested by the guidelines. 

Designing a Menu 

The Menu Manager works with strings of characters in order to 
build a menu and create its contents. A list of these strings is 
passed to the Menu Manager via the NewMenu Toolbox function. 
In machine language, C, or Pascal, the data for a menu list can be 
created by defining text-string constants. 

These strings must remain in memory for as long as the menu 
bar is present. Machine language programmers should not reuse 
the space occupied by these strings, and C programmers should de- 
fine the strings as global, static text. 
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A menu list consists of three parts: 

• A title 

• The menu items 

• The end of menu marker 

Additionally, each item of a menu, and its title, are tagged by a 
unique identification number. The ID number of a menu title is 
useful only to the Menu Manager. The ID number of a menu item 
is used by the application when the user selects a menu item. 

Figure 8-3 shows a sample menu list. 



Figure 8-3. Menu List 

» Waffle \N3 
— Apple\N256 
— Belgian \N257 
—Pecan \N258 
—Strawberry \ N259 



- Menu Title 



- Menu Items 



*■ End of Menu 



Each line in the list begins with two unique characters. The ex- 
ception is the last line which requires just one character. 

The first line in the list describes the title of the menu. It be- 
gins with two letters, numbers, or symbols. Following these charac- 
ters is the menu title. Incidentally, the title is usually surrounded 
by one or more spaces to provide padding between the other titles 
on the menu bar. The backslash character ( \) signals the end of 
the title and the beginning of the special characters. Therefore, a 
backslash cannot be part of the menu's name. The special charac- 
ters further describe the menu item. 

The commercial al symbol «§J) is used lo produce the colored 

Apple logo used for the Desk Accessory menu. It must be the only 
character in the title, with no surrounding spaces. 

You can also specify the (5) sign for any other menus you may 
have. However, only the Apple logo will appear as long as there is 
no other text along with it. 

The strings that follow the title line make up the list of items 
in this menu. Each line starts with the same two characters, which 
can be any characters, except the two that begin the menu's title 
line. The name of the menu item follows, and then finally, a 
backslash signals the start of the special characters. 
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A special menu item, called a dividing line, can be placed 
into the menu by using a single hyphen as a menu item. Its 
purpose is to divide members in an item list Dividing line 
items should be dimmed (see below) so that they cannot be 
chosen as a legal menu item. 



The very last line of the menu list consists of a single charac- 
ter This character must be different from the characters that start 
the menu item lines. However, it can be the same character that be- 
gins the title line, as shown in Figure 8-3 above. 

Each line in the list, except for the very last, ends with a car- 
riage return <$0D) or a null character ($00). This tells the Menu 
Manager that the end of the line has been encountered and it is al- 
lowed to proceed to the next line. 

The special characters that follow the backslash have the fol- 
lowing functions: 

Character Does This 

* Defines the command key equivalents 

B Draws the menu item's text in boldface 

C Places a character in fronl of the item name 

D Dims and disables the menu or menu item 

H Indicates that a two-byte hexadecimal ID number follows 

I Draws the menu item's text in italic style 

N Indicates that a decimal ASCII ID number follows 

U Underlines the menu item's text 

V Places a dividing line between this item and the next 

X Activates color replace for highlighting 

These characters can be upper- or lowercase. Two characters 
must follow the * for keyboard equivalents. They are used to spec- 
ify the case sensitivity of the command letter. For example: 

*Bb Both B and b are accepted 
*BB Only uppercase B is accepted 
*bb Only lowercase b is accepted 

Similarly, using •?/ would allow the user to press the Open 
Apple key and either the slash or question mark (shift-slash), for 
example, to execute a Help command. 
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The key equivalent will be displayed on the menu after an Ap- 
ple symbol. Also, only the first letter after the " is displayed on the 
menu, though both keys will work. 

The B, I, and U special characters, which stand for boldface, 
italic, and underline type styles, respectively, are used to enhance 
the display of text items. They may or may not be available for use 
depending on the system font. 

The letter C places a character before the item's text. Typically, 
this is used to mark the item with a special character, such as the 
following: 



Character 

Check mark 
Diamond 
Open Apple 
Solid Apple 



ASCII Value 

18 ($12) 

19 ($13) 

17(511) 

20 ($14) 



For example, to place a check mark before a menu item, the 
following string would be defined in a machine language source 
code file: 

dc c'~Chflcked ItemxCll'lB'.CNZBBV'.ll'O' 

More information on creating the menu strings from assembly 
language is covered in the next section. 

D is used to dim and disable an item. The item appears in a 
dimmed state and cannot be chosen. If the menu itself is disabled, 
every item in that menu will be dimmed and disabled. 

H and N allow a menu or item to be assigned an ID number. 
When H is used, it's followed by a two-byte hexadecimal value in 
low-byte/high-byte order. If N is used, it is followed by a string of 
decimal characters. Not every menu item requires an ID, and only 
certain IDs are used as shown in the following chart 

Menu IDs Description 

Used internally 

1-65534 Used by an application's menus 

65535 Used in tern ally 
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Item IDs Description 

Used internally 

1-249 Used by desk accessory items 

250 Undo 

251 Cut 

252 Copy 

253 Paste 

254 Clear 

255 Close 

256-65534 Used by an application's menu items 
65535 Used internally 

Identification numbers don't have to be sequential or defined 
in any order. They have to be unique, but only if they are enabled. 
Machine language programmers will want to assign menu item IDs 
starting with 256 and work upwards, not skipping over any values. 
(The reason for this is discussed later.) 

V is used to draw a dividing line between two items, across the 
entire width of the menu. It does not take up a line in the list of 
items, as the hyphen character does. (See above.) 

X uses color-replace mode that affects the way a menu is high- 
lighted when it is chosen. When a colored menu is selected with 
color replace activated, the colors will remain the same. For ex- 
ample, in the Apple menu, the X option should be specified. If not, 
the Apple character will appear gray on a black background, rather 
than colored on a black background. For ordinary menus, the X op- 
tion need not be specified. 

Creating Menu Strings 

When using the APW assembler, string constants are defined using 

the DC (Define Constant) directive: 

MenuS do o">> Waffle \N3',11'0' 

do o'~ Apple \ N2fi8'Aa\irO' 

do o'—Bsljlan S MSTBV.WV 

dc c— Paean \ M2B8*Pp',ll'0' 

dc C— Strawberry \ N269 , SeM'0' 

do c>' 

Each line ends with a single zero byte. ID numbers are as- 
signed using the special character N. However, the H character 
could have been used: 

do o 1 --Apple\H'.L'S&8',c"Aa',ll'0' 
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Why use H when N will do? Because it saves a byte and is 
easier for the Menu Manager to parse. Unfortunately, it makes the 
source code look messy. 

Things are done a bit differently using the C language. The 
Waffle menu could be defined using static text strings as follows: 

char 'Menu3[l = { "» Waffle \ \ KB", 
•■--Apple \ \ N2B6"Aa". 
"— Belgian \ N.N267W, 
"— Pecan \ \N2B8 , Pp", 
"—Strawberry \ \K2&9*Ss", 
">'■ }; 

Since the C compiler uses the backslash character for various 
purposes, it must be entered twice in a row in order to insert one 
backslash into a string of text. And since C strings by definition 
end in a null byte, the end-of-line terminator will be inserted auto- 
matically at compile time. 






An alternative method to define text strings is to use C's 
in-line assembly feature to define the strings with 65816 in- 
structions. Or you could write an external program in machine 
language that is linked with the C code later on. 




For programmers using TML Pascal, menu strings must be de- 
fined as global string types. They are built at runtime using the 
CONCAT function: 

Menu3 := C0NCAT('» Waffle \N3D\0'. 
'—Apple \N266'Aa\0\ 
'—Belgian \ N267*Bb \ 0', 
'— Peoan \ M256"Pp \ 0', 
'--Strawberry \ K259*Sb \ 0', 

Notice how each line is terminated by the null, \ 0, escape se- 
quence. Unlike C, Pascal strings are not automatically terminated 
by nulls, and, therefore, the programmer must provide them. 

Installing a Menu 

Before any Menu Manager functions can be called, the Menu Man- 
ager must be started. The Menu Manager, like a few other tool sets, 
also requires its own direct page. If you're not sure how to start up 





Chapter 8 



a tool set, or how to get direct page space, see Chapter 4 in this 
book, "About the Toolbox," and Chapter 7, "Memory 
Management." 

Placing a menu into the System Menu Bar is a two-step pro- 
cess. First, all menu strings must be passed to the NewMenu func- 
tion. NewMenu uses them to create an internal menu record. Once 
completed, NewMenu returns a handle to the menu record. 

The second step involves inserting the menu record into the 
System Menu Bar by using the InsertMenu function. This is done 
by passing the menu handle, returned by NewMenu, to 
InsertMenu. It then places the menu at the desired position. 

To accomplish this process from a machine language program, 
the following can be used: 



pha 




.long- word result space 


pha 




;long-word result apace 


pueblo rig 


*Menu3 


;polnt to Menu 3's strings 


-NewMenu 




;oreate the menu record . . , 

;. . . whoBe handle le now on the etaok 


push word 


*0 


insert it before all other menus 


—InsertMenu 







InsertMenu's two input parameters are the handle of the menu 
record and a position value that determines where on the menu bar 
the menu title will be inserted. If the position is 0, the menu will 
be the leftmost menu. Note how the menu record handle is kept on 
the stack for the call to —InsertMenu. 



The position argument, if 0, will insert the menu at the 
leftmost side of the menu, pushing any existing menus to the 
right. But if the position value is a Menu ID number, it in- 
structs the Menu Manager to insert the menu after the menu 
referenced by that ID. 



Creating and inserting a menu in C or Pascal is practically ef- 
fortless when compared to machine language. 
With C: 

lnsertMenu(NewMenu(Manu3[0]), 0); 

With TML Pascal: 

lnsertMenu(N9wMenu(0Menu3(l]), 0); 
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The two tasks can be taken care of with just one statement by 
embedding the NewMenu function within the InsertMenu function. 
This is a very common programming technique. 

TML Pascal requires the at symbol in front of the Menu3 vari- 
able in order to reference its address in memory. Also, the data in 
Pascal strings starts with element 1, because element is a count 
byte. 

Drawing the Menu Bar 

Even though a menu has been inserted into the menu bar, it does 
not appear on the screen. To cause the menu to appear, call the 
FixMenuBar function. 

In machine language: 

pna :word result spate 

—FixMenuBar 

pla 

ate Height 

Or in C: 



;p8turna the bar's height In pliels 
;(optlonal— you don't need to save It) 



Height = PliMenuBar( ); 

The Height assignment is optional. A simple FixMenuBar( ) 
alone can be used. 
In Pascal, 

Height : - FixMenuBar; 

does the same, but the variable assignment (Height) is required. 

FixMenuBar calculates the height of the System Menu Bar and 
vertical placement of menu items. This depends on the type of sys- 
tem font in use. If this function is not called, all the menu items 
will appear on top of each other, and the program will look 
peculiar. 

, Finally, when the menu records have been created, inserted, 
and fixed, the System Menu Bar can be displayed on the screen 
using the DrawMenuBar function. 

With C, use 

DrawMenuBarC ): 

Or with Pascal, use 

DrawMenuBar; 
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To perform the equivalent with a machine language macro call, 
use 

_DrawMenuBar 

This function displays the titles of all your pull-down menus 
on the menu bar. 

Using the TaskMaster 

The easiest way to manage your menus is to let the TaskMaster do 
all the work. The TaskMaster takes over whenever the user does 
something to affect the menu-bar area. As an example, if the user 
clicks the mouse over a menu title, the TaskMaster calls the func- 
tions in the Menu Manager that draws the menu on the screen. 

If the user begins to drag the mouse pointer down through a 
menu, TaskMaster calls the appropriate Menu Manager functions 
that allow the user to make a selection. TaskMaster also recognizes 
keyboard equivalents of menu items and treats them as if menu se- 
lections were made with the mouse. 

Before TaskMaster is used, your application must provide an 
event record where TaskMaster places information. The event 
record consists of seven fields, structured in this manner: 



EventRec 


anop 




;Bvent Record used by TaslsMaster 


What 


da 


2 


i,word 


Message 


da 


4 


;long word 


When 


de 


4 


.long word 


Where 


de 


4 


;long word 


Modifiers 


ds 


8 


;word 


TaskData 


da 


4 


;long word 


TaskMask 


do 


M'tinr 


;long word 



The address of this record is passed to TaskMaster as one of its 
arguments. 

Calling TaskMaster with machine language; 



pha 

pusbword **FF?F 

pustlong 'EventRec 

_ Task Master 

pla 



.Result Space 

JSvent Mask (screen all event types) 

;Polnt to Event Record 



;Gat Event code 
Calling TaskMaster with C: 
Event - TaBkMafltar(Oxnff, AEvantRec); 
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After calling TaskMaster, a code is returned to your applica- 
tion. If its value is not 0, an event is pending. The application can 
continue to call TaskMaster until a nonzero code is reported. This is 
demonstrated by the following loop in Pascal: 

REPEAT 

Event :- TaskMaster(tffff, EventRec); 
DMTIL Event <> 0; 

When the user eventually makes a menu selection, TaskMaster 
returns control to your application, informing it that an event has 
occurred. If a menu item (other than a desk accessory) has been se- 
lected, TaskMaster returns an extended event code of $0011 (17 
decimal). This is usually equated to the constant called 
wlnMenuBar, as shown in this Pascal statement: 

IP Event - wlnMenuBar THEN DoManu; 

The lowercase w in wlnMenuBar identifies it as a Window 
Manager constant. In TML Pascal, this constant is already defined 
as 17 for your application's use. 

When menu event $11 has occurred, tne menu number and 
menu item ID of the item selected can be obtained from the 
TaskData field in the Event Record. 

Table 8-2 shows the contents of the TaskData field and how 
each word is referenced from machine language, C, and Pascal. 
Some real-life examples follow, 



Table 8-2. TaskData Field 

Language Low-Order Word 

Menu Item ID 

Machine language TaskData 

C EventRec. win TaskData 

Pascal 



High-Order Word 
Menu Number 

TaskData + 2 

EventRec, wmTaskData<<t 6 



LoWord(EventRec.TaskData) HiWord(EventRec.TaskData) 

To retrieve the menu selection in machine language: 

Ida TaskData + 2 
sta MenuSelacted 

To retrieve the menu selection in Pascal: 

MenuSelected := HlWord(Evftntfac.TaBkData); 
To retrieve the menu selection in C: 

MenuSeleotad = EventRec. wmTaskData<<16; 
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The contents of the high- and low-order words of the TaskData 
field break down as follows: 

Low-order word The low-order word of TaskData holds the Menu Item 
ID of the selected item. For example, if the Pecan item 
in the Waffle menu were selected, the low-order word 
of TaskData would contain 258 (see Figure 8-3). 

High-order word The high-order word of TaskData contains the Menu 
Number. Again, if the Pecan item were selected, the 
high-order word of TaskData would contain 3. 

Dispatching Item Handlers 

Once the Item ID is known, as obtained from TaskData, the appro- 
priate action can be taken by the program. Suppose that when the 
user has selected the Pecan item from the Waffle menu, you want 
the program to execute the PecanWaffle routine. C and Pascal pro- 
grammers can use the SWITCH and CASE statements to do this. 
The CASE statement example in Pascal: 

CASE LoWord(EventRec.TaskData) OF 
S56 : AppleWaffls; 

26? : MjtuWaflle: 
288 : PecanWaffle; 
SB9 : StrawberryWaffls; 
BSD; 

PecanWaffle is a previously declared procedure. It fulfills the 
user's request, perhaps by bringing up a dialog box asking if 
whipped cream is desired on the pecan waffle. 

Dispatching the corresponding routine in machine language is 
done in one of two ways. The brute force method is to compare the 
item ID with an immediate value. If the two numbers match, a 
branch is made to the' appropriate subroutine. Otherwise, the pro- 
gram continues to compare the ID with other immediate values. 

A more elegant method, common among experienced machine 
language programmers, is to use the lower eight bits of the Item ID 
as an index into a table of pointers that point to the corresponding 
routines. It sounds more complex than it is. For example: 



Ida 


TaskData 


;Get TaskData Item ID number 


and 


•I0OFF 


.Discard upper 3 bits 


asl 


A 


; Double tbs value 


tax 




•.Transfer to X as an index 


J6r 


(MTabls,X) 


IDispatch the proper menu Item handler 
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If Pecan (item 258, the third menu item) were selected, the 
AND #$00FF instruction results in $02. This is multiplied by 2 
using the ASL instruction which produces $04. That value is trans- 
ferred to the X register to be used as an index. 



Using an index into a table of subroutines is one example 
of how useful numbering your menu items sequentially can 
be. The drawback is that during the cycle of development, 
you'll often move, reassign, insert, or change your menus as 
the program evolves. When this happens, renumbering menu 
items to keep them sequential can turn into a headache. 



MTable do 1' Apple Waffle' 

do rBelglanWaffle' 

dc l'PecanWaffle' 

do 1'StrawborryWaffle' 



;Itam 266 (X =< 0) 
litem 2B7 (X - 2) 
litem 358 (X = 4) 
;Ittm £B9 (X = 6) 



The JSR (MTable,X) instruction is known as an indexed, indi- 
rect jump to subroutine. The processor jumps to the two-byte ad- 
dress in MTable plus the value in the X register. Since X is 4, the 
subroutine PecanWaffle in the above table would be executed. 

Unhighlighting the Menu's Title 

During the dispatch of a menu item, the menu's title remains high- 
lighted on the menu bar. This reminds the user that a menu item is 
being handled. When the service routine is finished^ the menu's ti- 
tle should be inversed (unhighlighted). This is done with the 
HiliteMenu function. 

In machine language: 



puBhword 'FALSE 
pushword TaskData - 
-HUltoMenu 



;Unhlllte the menu title now 
;Push TaskData Menu number 



With TML Pascal; 
HMteMenu(FALSB. HJWord(EventReo.TaskData)}; 

And in C: 
HlllteMenu(PALSE, EventRec.wmTaskData»18); 
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The integer constant, FALSE, is defined as 0. 

Keep in mind that unhighlighting a menu item is not auto- 
matic. You must do it manually after each menu item's function is 
completed. 

Changing Menu Items 

Not only are menu items an excellent way to initiate subroutines in 
an application, but they can also be used to toggle certain states 
(flags) in your program. 

In a drawing program, for example, a check mark may appear 
next to the Ruler Guides item in the Tools menu. This would indi- 
cate that the rulers are in use. Should the user wish not to have 
rulers while painting {perhaps the artist is an impressionist), the 
Ruler Guides item could be selected from the Tools menu, which 
toggles the rulers off; the check mark would then disappear. But 
that doesn't happen by magic. 

Assume that Ruler Guides has a Menu Item ID of 268. To 
place a check mark to the left of its name in the menu, the 

CheclcMItom function ie need' 



pea 


TRUE 


:TRUE: yee, check the Item 


pea 


268 


;ltem 268 {Ruler Guides) 


Ids 


'I320P 


.CheckMItem 


JBl 


*E10000 






In C or 


Pascal: 



CheckMItem(TRUK. 268); 

Conversely, to remove a check mark or to make sure that there 
isn't one there, the same code can be used but with a FALSE value 
pushed to the stack instead of TRUE. 

If your program has many menu items with check marks, it's 
best to create one procedure responsible for updating the check- 
mark state of all the items. An example in C: 

UpdawCbeckMarkB( ) 

{ 

CheckMltem(RulerB. 268); 

CheckMIMm(BigBlt8, 270); 
CheckMItem(CtampB. 271); 
CheckMItem(WlndowLc-cks. 273): 

CheokMItem(ColorMode. 231); 
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The integer (or Boolean) variables Rulers, BigBits, Clamps, 
WindowLocks, and ColorMode contain values representing true or 
false for the states of those items. If, in this drawing program. Rul- 
ers are turned on, but in order to use them Clamps and 
WindowLocks must be turned off, this C function would handle 
the correct toggling of Rulers: 

ToggieRulersC ) 



Rulers — IRulers; 
If (Rulers) 

Clamps = WindowLockB — FALSE: 
UpdateCheckMarkaX ); 



/' Logics] NOT toggle '/ 



This is how the routine works: 

• Toggle the current Rulers state to its opposite. 

• If Rulers are now turned on (true), then make sure that Clamps 
and WindowLocks are turned off (false). 

• Finally, update all the check marks according to the new states. 

Another example of this technique, though not exactly similar 
to placing and removing the check mark, is the dimming of menu 
items, disabling them so that they cannot be selected. To disable a 
menu item, the DisableMitem function is used. 

In machine language: 

pushword *256 
—DisableMitem 

In C or Pascal: 

Dl8at>leMItem(25B); 

DisableMitem requires a menu item ID number as its argu- 
ment, After the call is made, that menu item will be dimmed and 
not available for selection. To enable the item once again, the 
EnableMItem is used in a similar fashion: 

In machine language: 

pushword *266 
—EnableMItem 

In C or Pascal: 

EnabieMltem(266); 
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Disabled menu items show up in a dimmed font in the pull- 
down menu, and the user of your program will not be able to select 
that item until it is enabled again, 

Setting Menu Flags 

Even though the Menu Manager has tools dedicated to one particu- 
lar task, the SetMenuFlag function can perform the duties of three 
functions in one. SetMenuFlag works on an entire menu and affects 
all of its items. The following examples show what a typical call 
looks like. 

In machine language: 

PushWord 'MenuFlag 
PushWord *MenuID 
_SetMenuFlag 

In C and Pascal: 

SetMemiFlag(M&nuFlag. M&nuID); 

The values and attributes for the MenuFlag argument are ex- 
pressed in Table 8-3. For example, using SetMenuFlag with $FFDF 
to invoke color-replace mode is the same as putting the special let- 
ter X in that menu's definition string. 

Table 8-3. Values and Attributes of the MenuFlag Argument 



;New menu flag value 
:Menu ID number 



MenuFlag Description Action 

SFF7F Enable Menu becomes undimmed and its items 

selectable. 
$0080 Disable Menu becomes dimmed and its items not 

available. 
$FFDF Color Replace Highlighting uses the color-replace method. 

$0020 XOR Highlight Highlighting uses the color XOR method. 

$FFEF Standard Defines the menu as a standard type. 

$0010 Custom Defines the menu as a custom type. 

Setting Item Flags 

While SetMenuFlag (discussed in the previous section) reigns over 
entire menus, the SetMItemFlag function allows the attributes of a 
single menu item to be modiFied. 

Table 8-4 provides a reference to the values that may be placed 
in the ItemFlag argument and their results. 
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Table 8-4. Values and Attributes of the ItemFlag Argument 
ItemFlag Description Action 

$FF7F Enable The item is enabled, selectable, and not 

dimmed. 
$0080 Disable The item is dimmed and disabled. 

$FFDF Color Replace Highlighting uses the color-replace method. 

$0020 XOR Highlight Highlighting uses the color XOR method. 

$0040 Underline The item is drawn with an underline. 

SFFBF No Underline The item is not underlined. 

This is how a machine language routine that places a value in 
an Item Flag would look: 



PushWord 
PuBhWord 



'ItemFlag 
'ItemID 



In C and Pascal: 



;Kew Item flag value 
litem ID number 



SetMenuFlagOtemFlag. ItemID); 

Of course, the EnableMltem and DisableMItem functions 
should be used for enabling and disabling menu items just to keep 
your code looking clean and logical. 

Menu Miscellany 

The rest of the chapter deals with some of the minor details of 
working with the Menu Manager. Everything from changing the 
blink rate of a selected menu item to removing an entire menu is 
discussed in this section. This is where the fun starts. 

Changing the Text Style 

Menu items can appear in the standard text face or in special styles 
set by using the SetMltemStyle function. The normal system font 
can be displayed only in a bold style. However, the Toolbox has 
provisions for italic, underline, outline, and shadow styles when 
used with compatible fonts. 

This brief table describes the effect of entering various values 
in the Style Word: 

Style Bits Style 

Bold 

1 Italic 

2 Underline 
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Style Bits 
3 

4 
5-15 



Style 
Outline 
Shadow 
Reserved 



If a bit is set in the Style Word, it asserts that attribute. The 
following examples will set a hold style on the text of a menu item, 
In machine language: 

PushWor-d *1 ;Bold 

PushWord *282 ;Item ID 
_SetMItemStyle 

In C and Pascal: 

S9tMItemStyIe(l. 262); 

To modify only one style bit without changing the others, use 
the GetMItemStyle function to return the current style, manipulate 
the appropriate bits, and then update the item with SetMItemStyle 
This C language example sets a bold style to item #262 without 
changing any of its other style attributes: 

/' Style Is an unsigned Integer •/ 



Word Style; 
Style = GetMItemStyl8(2e2); 
Style = Style 1 1; 
SetMltemStyle(Sty]e, 262); 



/■ Get the ourrent style •/ 
/• Logically OH with 1 '/ 
/• Set the new style 7 



Or, the most compact form could be used: 
SetMItemStyle(GetMItemStyie(262) 1 1. 262): 

Renaming a Menu Item 

It's common to change the name of a menu item. In most cases, re- 
naming an item draws a close relationship to using a check mark to 
show a certain state. For example, say you've written a communi- 
cations program in which one of the items on a menu is Text Edi- 
tor. By choosing this item, a user of your application is taken out of 
terminal mode and is placed into an editor mode. This would be an 
opportune time to rename that menu item, since Text Editor is no 
longer a valid choice: The user is already in it. Instead, that item 
could be renamed to Terminal Mode. By selecting this, the user 
could leave the editor and return to the terminal mode. 
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Changing the name of a menu item is quick and easy, as 
shown in these examples. 
In machine language: 



PushLoog 'NewName 


; Point to the 


new title 


PushWord *262 


iSpeolfy the 


item ID 


-SetMItem 


;Change the Item's name 


rts 






NewName dc C— Terminal Hode',11'0' 




In Pascal; 






PROCEDURE NameMltem; 






VAR 






NewName : String: 






BEGIN 






NewName : = ' — Terminal Mode \ 0' 






SeiMItem<<BNewName[l], 262); 






END; 







In C: 

SetMItemC— Terminal Mode", 262); 

The SetMItem function requires two arguments: 

• The address of a menu item string 

• An integer that represents the ID of the item to rename 

The string containing the new name is formatted just like a 
menu item: It begins with two starting characters (used only by the 
Menu Manager), and it ends with a null character. 

Recall that strings in C always end with a null character. 
Therefore, there is no need to explicitly add one to the initialization 
string in the C example above. 

SetMItem changes only the name of the item. All previous 
attributes— such as style, enabled or disabled states, and so on — 
are preserved. Even if the new item string contains a backslash ( \) 
followed by special characters, only the name will be replaced. You 
can change attributes by using other Menu Manager functions dis- 
cussed throughout this chapter. 

Pascal users will undoubtedly want to use SetMltem's cousin, 
SetMItemName which is similar in syntax. The difference is that 
SetMItemName accepts a pointer to a Pascal string. Remember that 
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strings in Pascal always start with a count byte. Here is an alternate 
Pascal example using SetMltemName: 

SetMItemNameC'Termlnal Mode'. 262); 



SetMItem is used to change the Save menu item in most 
Apple IlGS programs. After a file is opened, the Save item 
reads Save DOCUMENT, where DOCUMENT is the name of 
the file the user has opened. Simple string concatenation func- 
tions can be used in conjunction with SetMItem to accomplish 
this. 



Although you've renamed the menu item, you're not done 

just yet. 

When an item is renamed, the menu in which the item resides 
must adjust itself to the new width of the item, especially if it is 
longer than any of the others. This is done by using the Calc- 
MenuSize function as demonstrated below. 

In machine language: 



PushWord *0 
PuflbWord "0 
PushWord *2 
_CalcMenuSlze 



;Nsw Width (0 ■ auto adjust} 
;Kaw Height (0 = auto adjust) 
;Ttae Menu's ID (not Item IDI) 



C and Pascal: 
CalcMenuSIze(0. 0, 2); 

CalcMenuSize, when used with nonzero arguments, can be 
used to set a menu's explicit height and width in pixels. If 0's are 
used, the Menu Manager will scan through the menu strings and 
automatically calculate the size of the menu, with room for check- 
marks and Apple key equivalents. CalcMenuSize requires the ID of 
a menu as its third argument. 

If the menu width is not resized, long menu item names will 
bleed right off the edge of the menu and into the DeskTop, which 
looks messy. 

Renaming a Menu 

It is far less common to change the title of a pull-down menu, but 
the Menu Manager will let you do it. The procedure is similar to 
changing a menu item's name. 
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Study this machine language routine: 



Pushlong 'NewName 
PushWord *Z 

_SetMenuTltle 

—DrawMenuBar 

rte 



lAddresa of title 
;Menu ID number 
;Change the title 
:show the change 



NewName atr ' Modem ' ;PaBcal-8tyle string 
The same routine in Pascal: 

SatMenuTltleC Modem '. 2); 
DrawMenuBar; 

The same routine in C: 

SetMentiTltle("\p Modem ", 2); 
DrawMenuBar ( ); 

SetMenuTitle requires two arguments: 

The address of a Pascal string 



• A Menu ID number 



Since a Pascal string is needed, the only language that doesn't 
have to do anything unusual with the string is, of course, Pascal, 
The machine language example uses the Str macro, while the C ex- 
ample uses the \p string escape in order to put a count byte 
before the new menu title string. 

After the title is changed, use DrawMenuBar to show off your 
handiwork. 

Now You See It . . . 

Another rarely used feature of the Menu Manager is the ability to 
insert both menus and menu items into an existing menu structure. 
This is accomplished with the InsertMenu and InsertMltem func- 
tions, respectively. InsertMenu was discussed in detail earlier in this 
chapter. 

To insert a menu item, InsertMltem is used in the following 
machine language example: 



PushLong 'Newltem 

PushWord *IFFFF 
PushWord *2 
—InsertMltem 
rta 



;address of Item string 
;make It the last Item 
;ID of the Menu to use 

; insert It 



Newltem do C— New Item\N381DMl'0' 
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In Pascal: 

PROCEDURE inBertNewItem; 
VAR 

Newltem : String; 
BEGIN 

Nflwltem := '—New ltem\N281D\0'; 

InflertMlWm(0Newltem[l], IfffT, 2); 
END; 
InC: 

In8ertMItem("--N8W ItomMMBlD", Oxffff, 2); 

InsertMItem's three arguments are 

• The address to a complete menu item string 

• The position where the item should be inserted 
- The ID number of the menu to use 

Values for the position (second) argument are 

Position Description 

$0000 Insert into the menu before all other items 

SFFFF Insert into the menu after all other items 

ItemID Insert after the specified Menu Item ID 

As described earlier, CalcMenuSize should be called after in- 
serting a new menu item. 

. . . Now You Don't 

If the Toolbox allows you to insert menus and menu items, there 
must also be a way to delete them. DeleteMenu and DeleteMltem 
are practically identical in syntax. They both require a single input 

parameter; 

• A menu ID number for DeleteMenu 

• An item ID for DeleteMltem 

To delete an entire menu in machine language, use 

PushWord •MenuID :the ID of the menu to delete 
_DeieteMenu ;it'& gonel 

Using C and Pascal: 

De]eteMenu(MenuID); 
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To delete a menu item in machine language use 



PushWc-rd 'ItemID 
—DeleteMltem 



;the ID of the Item to delete 
;poofl 



In C and Pascal: 

DeleteMItem(ItemlD); 

Change Slink Rate 

After a menu item is selected, the item winks at you a few times 
before your choice is acted upon. The number of times the item 
blinks is determined by the blink rate. Usually, this value is set to 3 
upon starting the Menu Manager. But you can spring the following 
routine on some unsuspecting user. 
In machine language: 



PuahWord *BQ 
-SetMItemBllnk 



;blinfc 60 tlmesl 



In C and Pascal: 

SfltMItemBlInli(BO); 

When SetMItemBlink is used to change the blink rate to 50, a 
selected menu item will flash on and off 50 times before the item is 
handled. 

Menu Bar Colors 

If you're enthralled by the myriad of colors your Apple IIGS can 
produce, you'll be happy to know that even the menu bar can 
show its true colors. The text, background, and outlining can be set 
to any of 16 different colors in 320 mode, and 4 colors in 640 
mode. Even though the colors can be changed in 640 mode, it's 
hardly worth the trouble because so few colors are available. But in 
320 mode, the effects can be quite interesting. 

How about a blue background, yellow text, and red outlines? 
Use the MODEL program from Chapter 6 and insert the following 
code just before the DrawMenuBar function is called. 

In machine language: 



PuBhWoM **4G 
PushWord *I94 
PuahWord «I70 

-SetBarColors 



Background and text colors 
Background * text for color replace 
Outline color 
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InC: 

SelBarColoP8(0i49, 0x94, 0x70); 

In Pascal: 
SstB4PColors(l49. *94, 470); 
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To get blue, yellow, and red menu bar colors, the 
QuickDraw tool set will have to be started up for 320 mode. 
To do this, use a MasterSCB (screen mode) value of $00. Also, 
make sure to specify a maximum X clamp of 320 pixels when 
starting the Event Manager. 





Colors 




per Mode 


Value Name 


320 640 


NewBarColor 


16 4 


NewInvertColor 


16 4 


NewOutColor 


16 4 



SetBarColors uses three input values: 



Description 

Background (bits 4-7), text (bits 0-3) 
Color-replace values for background /text bits 
Outline color (bits 4-7) 

All unused bits are 0, except for bit 15, the most significant bit. 
This bit is used to cancel the effects of a value. In other words, 
your program could establish a new outline color, but leave the text 
and background colors as they were by setting bit 15 on the New- 
BarColor and NewInvertColor arguments. 

When the modified MODEL program runs with new menu col- 
ors, the menu bar will be dark blue with yellow text. The outline 
around the menus, dividing lines, and underlines wilt be red. But 
selected menus and items will appear in light blue with orange 
text. 

The Apple menu will retain its colorful logo, but on a yellow 
background. Why? Recall that the Apple menu uses the special 
character X in its menu string. This denotes a color-replace mode 
when selected. All other menus and their items use an XOR (exclu- 
sive OR) method of highlighting when selected. 

It's clear to see why this occurs by examining Table 8-5. The 
color number for dark blue is 4. When XORed with its complement 
(EOR #$FF), the result is 11, which corresponds to light blue. Like- 
wise, yellow (9) XORed with its complement results in orange (6). 
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Table 8-5. Standard Colors in 320 Mode 



Color 


Number 


Black 
Dark Gray 

Brown 



1 

2 


Purple 
Dark Blue 


3 
4 


Dark Green 

Orange 

Red 


5 
6 

7 


Beige 
Yellow 


8 
9 


Green 


10 


Light Blue 
Lilac 


n 

12 


Periwinkle 


13 


Light Gray 
White 


14 

15 



The second argument, NewInvertColor, is applicable only to 
color-replace items. So in order to cause selected items to appear in 
blue text with a yellow background, the opposite of their back- 
grounds when not selected, the special X character would have to 
be placed in each item's menu string. 

With a little creativity, you could create a menu where only se- 
lected items would show up in a color, indicating a warning or 
other message to the user, based on the color. 

There are accepted guidelines governing the use of color in 
programs. See Appendix A, "Human Interface Guidelines," for 
more details. 

Chapter Summary 

The following tool set functions were referenced in this chapter: 

Function: S01 OF 

Name: MenuBootlnit 

Initializes the Menu Manager 

Push: nothing 

Pull: nothing 

Errors: none 

Comments: Do not make this call. 
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Function: 


$02OF 


Name: 


MenuStartUp 




Starts the Menu Manager 


Push: 


User ID (W); Direct Page (W) 


Pull: 


nothing 


Errors: 


none 


Function: 


$030F 


Name: 


MenuShutDown 




Shuts down the Menu Manager 


Push: 


nothing 


Pull: 


nothing 


Errors: 


none 


Comments: 


Make this call when your application is finished. 


Function: 


S0D0F 


Name: 


Insert Menu 




Inserts a menu into the menu bar 


Push: 


Menu Handle (L)j Insert After (W) 


Pull: 


nothing 


Errors: 


none 


Comments: 


If Insert After is 0, the menu becomes the first in the menu 




bar. 


Function: 


$0E0F 


Name: 


DeleteMenu 




Removes a menu from the menu list 


Push: 


Menu Number (W) 


Pull: 


nothing 


Errors 


none 


Comments 


Use DrawMenuBar to update the screen. The menu is not 




fully disposed, just deleted from the list. 


Function 


$0F0F 


Name 


InsertMItem 




Inserts a menu item into a menu 


Push 


Item (L); Insert After (W); Menu Number (W) 


Pull 


nothing 


Errors 


none 


Comments 


If Insert After is 0, the item becomes the first in the menu. 


Function 


$100F 


Name 


DeieteMltem 




Removes an item from a menu 


Push 


[tern (W) 


Pull 


nothing 


Errors 


none 


Comments 


. Use CalcMenuSize after making this call. 
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Function: S130F 

Name: FixMenuBar 

Standardizes the menu bar's sizes and returns its height 
Push: Result Space (W) 
Pull: Height (W) 
Errors: none 
Comments: The returned height is in pixels and is usually 13. 
Function: $170F 

Name: SetBarColors 

Specifies the colors of the menu bar 
Push: Normal Color (W); Selected Color (W); Outline Color (W) 
Pull: nothing 
Errors: none 

Function: S1C0F 

Name: CalcMenuSize 

Calculates the new dimensions of a menu 
Push: Width (W); Height (W); Menu Number (W) 
Pull: nothing 
Errors: none 

Function: S1F0F 

Name: SetMenuFlag 

Specifies the attributes of a menu 
Push: Attributes (W); Menu Number (W) 
Pull: nothing 
Errors: none 
Comments: Attributes are: $FF7F = Enable, $0080 - Disable; SFFDF - 
Color Replace; S0020 - XOR Highlight; $FFEF = Standard; 
$0010 = Custom. 

Function: $21 OF 

Name: SetMenuTitle 

Selects the title for a menu 
Push. Title (L); Menu Number (W) 
Pull: nothing 
Errors: none 

Function: 5240F 
Name: SetMItem 

Selects the name for an item 
Push: Name (L); Item Number (W) 
Pull; nothing 
Errors: none 
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Function: S260F 

Name: SetMItemFlag 

Sets the attributes of a menu item such as being underlined, 
enabled, and so on 
Push: Attributes (W); Item Number (W) 
Pull: nothing 
Errors: none 
Comments: Attributes are: $0040 = Underline, SFFBF = No Underline, 
$0020 - XOR Highlight; $FFDF - Redraw Highlight; $FF7F 
- Enable; $0080 = Disable. 



Function: 

Name: 

Push: 

Pull: 

Errors: 

Function; 

Name: 

Push: 
Pull: 

Errors: 

Function: 
Name: 

Push: 

Pull: 

Errors: 

Comments: 

Function: 
Name: 

Push: 

Pull 

Errors 

Comments 



$280F 

SetMltemBlink 

Sets the blink rate for selected items 

Blink Count (W) 

nothing 

none 

S2A0F 

DrawMenuBar 

Draws the menu bar and its titles 

nothing 

nothing 

none 

$2C0F 

HiliteMenu 

Determines if a menu title is highlighted 

Hilite Flag (W); Menu Number (W) 

nothing 

none 

If Hilite Flag is nonzero, the title is highlighted; otherwise, 

it's unhighlighted. 

$2D0F 
NewMenu 

Creates a new menu 
Result Space (L); Menu Structure (L) 
nothing 
none 

This creates the menu internally and does not display or in- 
sert it into a menu bar. 
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Function: $300F 




Name: EnableMttem 




Enables a disabled menu item 




Push: Item (W) 




Pull: nothing 




Errors; none 




Function: $31 OF 




Name; DisableMltem 




Disables a menu item, making it dimmed 




Push: Item (W) 




Pull: nothing 




Errors: none 




Comments: The item will no longer be available for selection. 




Function: $320F 




Name; CheckMItem 




Manages check marks for a menu item 




Push: Check Flag (W); Item (W) 




Pull: nothing 




Errors: none 




Comments: An item will be marked with a check if Check Flag is 


true; a 


check will be removed if false. 




Function: $330F 




Name: SetMltemMark 




Sets the marking character (or none) for an item 




Push: Mark Character (W); Item Number (W) 




Pull: nothing 




Errors: none 




Comments: Use for no mark. 




Function: $350F 




Name: SetMItemStvle 




Sets the text style of a menu item 




Push: Text Style (W); Item Number (W) 




Pull: nothing 




Errors: none 




Function: $3A0F 




Name: SetMltemName 




Selects a name for a menu item 




Push: Name (L); Item Number (W) 




Pull: nothing 




Errors: none 




Comments: Name is a Pascal-type string. 
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Windows 

Next to pull-down menus, win- 
dows are the most important 
part of the desktop environ- 
ment, A window is a region of 
the screen inside of which infor- 
mation and/or graphics can be 
displayed. The Toolbox's Win- 
dow Manager provides the func- 
tions for creating a window and 

placing variou§ obj§ct§ into it. 
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This chapter covers programming, creating, and using Apple 
lies windows P Unfortunately, not everything about wmdowscan 

order. 

A Frame to Build On 

Windows are controlled by a joint cooperation between the Wm- 
Tow Meager and the Control Manager. The Window Manager* 
what actually manages the windows (as you ^dlf^" 
also takes care of certain functions that occur behind he scenes 
The Control Manager is responsible for all the controls on a wm- 
low Co^trol^e fhe buttons, boxes, scroll bars, and other items 
fhaT aUow^u to manipulate a window. Therefore, both managers 
share the responsibility of windows on the desktop. 

ager and then the Control Manager. 

The Window Record 

Once all your tool sets have been started, placing a window on the 

? c "en n't a difficult task. In fact, you simply pass mformation 

about the window to a Window Manager Toolbox function Jhe 

window's information is kept in one of the ^J£"£££ old 

hires used by the Toolbox, the window record. The window record 

^ores al sons of informal about the window, its 

coTor types of controls, movability, ability to zoom, and large 

niiantities of additional information. 

" Unlike the Menu Manager, which uses several intervening 

steps between creating the menu and having ^PP"'^* 

screen the NewWindow function displays a window i™ed«lely^ 

^i, have to do is point to your window record so NewW.ndow 

can find it. 
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NlewWindow returns a long pointer to your window's port in 
memory after a successful Toolbox call. Use this pointer to refer- 
ence the window. For example, to close the window, the port ad- 
dress for that window is pushed onto the stack and a Toolbox call 
is made to the CloseWindow function. All other Window Manager 
calls use the port pointer, and there is a port for each window on 
your desktop. 

Things in a Window 

When you're creating a window, you should be familiar with alt 
the controls it uses, and with what each control does. These con- 
trols are summarized in Figure 9-1. 

Figure 9-1. Diagram of Window with Controls 
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The controls and items inside a window are explained below. 
All of these items are optional: A window need not contain any of 
them. 

Bottom scroll bar. The bottom scroll bar moves the contents of 
the window right or left. 

Close box. The close box is used to remove the window from 
the desktop (to make it disappear). This is not a direct function of 
this control. Your program actually makes the window close. Clos- 
ing a window is covered in detail later in the chapter. The close 
box control is located in the title bar 



Grow box. The grow box is used to resize the window. The 
grow box can be grabbed with the mouse and moved to change the 
horizontal and vertical dimensions of the window. 

Info bar. The info bar appears just below the title bar and is 
used to display additional information about the window, The Ap- 
ple lies Finder program makes extensive use of window info bars 
to let you know how many files are present in each window, and 
so on. 

Right scroll bar. The right scroll bar moves, or scrolls, the 
contents of the window either up or down. Only if a window has 
contents larger than can be seen through the window does it need 
a scroll bar. 

Title. The title is the name of the window, centered in the title 
bar. 

Title bar. The title bar shows the title of the window, The title 
bar also contains the optional close box, or go-away button, and the 
zoom button. The title bar is used to drag the window around the 
desktop, Because of this it's also referred to as the drag region of 
the window. 

Zoom box. The zoom box can be used to make the window 
expand to fill the entire screen. Clicking the zoom a second time 
restores the window to its previous size. Both sizes, original and 
zoomed, are determined by the Window Record at the time the 
window is created. 

When you're creating a window, all these items are specified 
in the window record. Depending on what type of data is in the 
window and how you want it displayed, any number of these op- 
tions can be specified. 

The TaskMaster 

No discussion of windows and controls would be complete without 
mention of the TaskMaster. TaskMaster is a Window Manager 
function that acts as an extension of the Event Manager. It's espe- 
cially handy when you're dealing with windows. Though the Task- 
Master is discussed elsewhere in this book, it's important to know 
the window-related event codes returned by TaskMaster. 

The following table shows the extended event codes and regu- 
lar event codes returned by the TaskMaster function. Note that ex- 
tended events 2-12 concern themselves with windows. 
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Table 9-1. Event and Extended Even! Codes Returned by TaskMaster 



Event Code 


Extended Code 


Description 


16 





Mouse is in desk 


17 


1 


A Menu item was selected 


18 


2 


Mouse is in the system window 


19 


3 


Mouse is in the content of a window 


20 


4 


Mouse is in drag region 


21 


5 


Mouse is in grow 


22 


6 


Mouse is in go-away 


23 


7 


Mouse is in zoom 


24 


8 


Mouse is in info bar 


25 


9 


Mouse is in vertical scroll 


26 


10 


Mouse is in horizontal scroll 


27 


11 


Mouse is in frame 


28 


12 


Mouse is in drop 



When one of these events takes place, the event code is re- 
turned by TaskMaster. The window associated with the event can 
be determined by examining the TaskData field of the event record. 
For example, if your desktop had many windows on it and you 
clicked the go-away button in one of them, that window's pointer 
would be placed in TaskData. The window can be further manipu- 
lated by Window Manager functions that use the window pointer, 
(A good example of this is in the MONDO program listed at the 
end of this chapter.) 

The important thing to remember about TaskMaster is that it 
assists in the trapping of window-related events, It also automati- 
cally updates the contents of a window as you scroll them around. 

Opening a Window 

Putting a window on the screen is a trivial task. A simple call to 
the Toolbox is all that is required, The complexity of the window 
lies in the window record — a group of values, ranges, and pointers 
that actually define the window. 

For example, suppose you wanted to display a typical Apple 
lies window. To do this you need two things: 

• A call to the Window Manager's NewWindow function 

• The window record describing the window 
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In machine language, the call looks something like this: 



pha 




;Long result apace 


pha. 






pushlong 


♦WindowRec 


; Address of window record 


-NewWindow 




;the new window call 


Jsr 


ErrorH 


iReraember to do error checking 


pulllong 


WlndowPtr 


;A pointer to the window 



First, a long word of result space is pushed to the stack, fol- 
lowed by the address (long) of the window record. Then the call is 
made to NewWindow. After the call, the Toolbox returns a pointer 
to the window's record. All further reference to the window is 
made through this pointer, so it should be saved in memory. (The 
above routine saves the pointer at the label WindowPtr.) 

The only possible errors at this point are $0E01 and S0E02. Er- 
ror $0E01 is produced if the window record is of an unusual length 
(meaning you left something out or the pointer was inaccurate). Er- 
ror $0E02 is a memory error and probably would only happen if 
your computer didn't have a memory upgrade or if you had too 
many windows already open. 



A typical error in working with structures in machine lan- 
guage, especially if you're using macros, is to reference the ad- 
dress of a structure incorrectly. For example, the following 
pushlong macro is in error: 

pushlong WindowRec ;Thls Is wrong 

Because the # in front of WindowRec is left off, the program 
attempts to push the long value that resides at WindowRec. 
This is akin to leaving off the ampersand (&) before a variable 
in a C program. 

What is intended is that the address of WindowRec (its lo- 
cation in memory) be pushed onto the stack. The address of 
any object is always referenced as an immediate value. Thus, 
the following is the correct ivay to push the long address of a 
structure or label in memory: 

pushlong 'WindowRec ;Thls Is the oorfsot way 



.. 
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In C, the following routine can be used to summon up a new 
window: 

WlndowPtr = NewWtndow(&WlndowRec); 

And in Pascal: 

WlndowPtr := NewWlndow(WlndowRBo); 

As was mentioned earlier, the hard part (if you want to call it 
that) is creating the window record, It contains a wealth of infor- 
mation about the window and is perhaps the most detailed record 
used by the Tool box. The window record is covered later in this 
chapter. 

Closing a Window 

All that's needed to close a window is the pointer to the window 
record and, of course, a call to the Window Manager's 
CloseWindow function. After CloseWindow is called, the window 
is removed from the screen and all the data contained in the win- 
dow is gone. Using the pointers returned from the NewWindow 
call in the previous section, the following code examples are used 
to close a window referenced by Window Ptr. 
In machine language: 



pusnlong 
—CloseWindow 



WlndowPtr 



;Saved when the window was opened 
;(No errors are possible here) 



In C and Pascal: 

CloseWtndow(WlndowPtr): 

After CloseWindow, the window disappears from the screen, it 
is removed from the current list of windows, and any data con- 
tained in the window is lost. A window doesn't have to be on top 
of all the other windows in the desktop, nor does it have to be ac- 
tive in order to be removed. 

It's important to note that clicking in a window's close box 
does not automatically close the window. Nor does selecting a close 
window option from a pull-down menu. Closing down a window 
has to be done by the code in your program. 

To detect when the close box has been clicked, you must use 
the Window Manager's TaskMaster function. The extended event 
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codes returned by the TaskMaster call are your clues as to what is 
going on in a window. Normally, most of the operations (scrolling, 
growing, moving, zooming, and so on) are taken care of automati- 
cally by the operating system. But your program will have to moni- 
tor the close box, 

Extended event code 6, or regular event code 22, is returned 
by the TaskMaster call when the mouse is clicked in the close box 
(see Table 9-1). When extended event code 6 is returned, the cor- 
responding window's pointer is found in the TaskData field of the 
event record. To close the window, the following machine lan- 
guage code can be used: 



pushlong 
—CloseWindow 



TaskData :get window's pointer from TaskData. 



The window record, placed in TaskData by the TaskMaster, is 
pushed to the stack for the CloseWindow call. This is the same as a 
regular close, except the window pointer is snatched from 
TaskData. 

As usual, the examples for C and Pascal are a little more 
straightforward. 

InC: 

CloseWlndow(EventReo.wmTaskData); 

In Pascal: 

CloseWlndow(WlndowPtr(EventRec TaskData)); 

This method of using TaskData works even when there are a 
number of windows present on the desktop. 

The Window Record 

The window record defines the window, determines what the win- 
dow can do, and establishes which controls (zoom, grow box, title 
bar, and so on) the window will have. The window record is 
huge — 24 parameters determine what type of window is created. 
In the following table, the parameter name is the word used 
by Apple in all documentation to refer to that particular parameter 
of the window record. Later on, when a sample window record is 
created, a few of the parameters will be combined into one to make 
the list easier to manage. 
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Table 9-2. The Window Record's Parameter List 




Parameter Name 


Type 


Description 




paramlength 


Word 


Size of this table 




wFrame 


Word 


Bit pattern describing the frame 




w Title 


Long 


Window's title 




wRefCon 


Long 


User-defined value, usually 




wZoom 


Rectangle 


Size of window when zoomed 




wColor 


Long 


Window's color table location 




wYOhgin 


Point 


Window content's origin, Y position 




wXOrigin 


Point 


Window content's origin, X position 




wDataH 


Word 


Height of document 




wDataW 


Word 


Width of document 




wMaxH 


Word 


Maximum height for grow window 




wMaxW 


Word 


Maximum width for grow window 




wScrolIV 


Word 


Number of Y pixels to scroll 




wScrollH 


Word 


Number of X pixels to scroll 




wPageVer 


Word 


Number of Y pixels to page 




wPageHor 


Word 


Number of X pixels to page 




wlnfoRefCon 


Long 


Used by info-bar draw routine 




wlnfoHeight 


Word 


Height of info-bar 




wFrameDefProc 


Long 


Window definition procedure 




wlnfoDefProc 


Long 


Info-bar drawing routine 
Content drawing procedure 




wConlDefProc 


Long 




wPosition 


Rectangle 


Window's starting coordinates 




w Plane 


Long 


Position, front to back 




wStorage 


Long 


Memory for window record 




Incidentally, the tiny W at the 


front of a parameter name is an in- 




stant tip-off that the parameter belongs to the Window Manager, 




Each of the parameters is discussed in detail in COMPUTERS 




Mastering the Apple UCS Toolbox. However, the following is a brief 




rundown of each 


of them, along with explanations and expansions 




where necessary. 








paramlength 


The parameter paramlength (word value) is the 




length of the entire window record. It's used by the Memory Man- 




ager in moving these parameters to the internal window record. It 




also serves as a form of error 


checking: If the paramlength is inac- 




curate, the Window Manager 


returns an error code of S0E01 after 




the New Window call. 






1 
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wFrame. The parameter wFrame (word value) describes the 
frame of the window. Each bit in the word wFrame signals the 
presence or absence of one of the window controls. A window with 
everything on it has the following bit pattern: 

1101111110100000 

which is $DFA0 in hex. The individual significance of each of the 
bits is shown in Table 9-3. 

Table 9-3. wFrame Values 

Bit If set, means 

The window is highlighted (initially always 0) 

1 Window is zoomed when first drawn 

2 Internal use (determines window record allocation) 

3 Window's controls can be active when the window is inactive 

4 The window has an info bar 

5 The window is visible 

6 An inactive window is made active if the mouse is clicked in it 

7 The window can be moved (bit 15 should also be set) 

8 The window has a zoom box (bit 15 should also be set) 

9 The size of the window is flexible (grow and zoom will not change 
the origin of the window's data) 

10 The window has a grow box (bit 11, bit 12, or both should also be 
set) 

1 1 The window has an up- and down-scroll bar (right side) 

12 The window has a left- and right-scroll bar (bottom) 

13 The window has a double frame, like an alert dialog box 

14 The window has a go-away button (bit 15 should also be set) 

15 The window has a title bar 

The bits above that are set to define a window "with the 
works" are 5, 7, 8, 9, 10, 11, 12, 14, and 15. Bit 13 is used by the 
Dialog Manager when it creates a window. Bits 4, 8, 9, 10, 11, 12, 
14, and 15 must be reset to if this bit is set. 

wTitle. wTitle (long pointer) points to the memory location 
containing the window's title. The title is a Pascal string, and it's a 
good idea to pad it with spaces. (This keeps the title from appear- 
ing too tight in the title bar. More on this in a while.) If a long 
word of is specified, the window has no title. 
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wRefCon. wRefCon (long value) is a user-defined value, 
though typically a long word of is specified. A few of the Win- 
dow Manager's functions can return or set this value, but its mean- 
ing is up to you. For example, in the sample program, MONDO, 
wRefCon is used to number each window for later reference in the 
program. 

wZoom. wZoom (rectangle) indicates the size of the window 
when zoomed. The four word values are listed in the order MinY, 
MinX, MaxY, MaxX. If four words of are specified, the entire 
screen is filled with the window. It's also suggested your window 
have a zoom box (bit 8 of wFrame above). 

wColor. wColor (long pointer) points to a table controlling the 
color of the window, title bar, and frame. If a long word of is 
specified, the system default colors are used. (See the section on 
color later in this chapter for additional information.) 

wYOrigin and wXOrigin. wYOrigin (point) and wXOrigin 
(point) set the Y and X origins of the window's data. Both Y and X 
are word values, expressed in global coordinates (with 0, as the 
upper left corner of the screen). In this book, both wYOrigin and 
wXOrigin together are referred to as the point value wOrigin. 

wDataH and wDataW. wDataH (word) and wDataW (word) 
designate the height and width of the data inside the window. If 
the data cannot be scrolled (meaning the window doesn't have 
scroll bars), two words of are used. wMaxH (word) and wMaxW 
(word) specify the maximum height and width of the window. The 
size of the window is manipulated by the window's grow box and 
is measured in pixels. 

wScrollV and wScrollH. wScrollV (word) and wScrollH 
(word) define the number of Y and X pixels, respectively, that a 
window may scroll when the arrows are clicked in either the 
up/down or left/right scroll bars. 

wPageVer and wPageHor. wPageVer (word) and wPageHor 
(word) define the number of Y and X pixels that a window is 
paged. Paging occurs when the mouse is clicked inside a scroll bar, 
(This should be a proportionally larger value than for wScrollV arid 
wScrollH, above.) 

wlnfoRefCon. wlnfoRefCon (long pointer) points to a string to 
be placed in the window's information bar. If there is no string, it 
points to a long word of 0. (The window should have an infor- 
mation bar for this value to take effect — bit 4 of wFrame above.) 
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wlnfoHeight. wlnfoHeight (word) defines the height, in pixels, 
of the window's information bar. As with wlnfoRefCon, the win- 
dow should contain an information bar for this value to have any 
meaning. 

wFrameDefProc. wFrarneDefProc (long pointer) points to a 
window definition routine or procedure. It is normally set to a long 
word of to use the default routines. 

wlnfoDefProc. wlnfoDefProc (long pointer) points to a routine 
that draws the window's information bar, or it points to a long 
word of if no info bar is present in the window. 

wContDefProc. wContDefProc (long pointer) contains the ad- 
dress of a routine that draws the contents of a window. An ex- 
ample of such a routine is listed in the section "Window Contents" 
later in this chapter. If no routine is used, a long word of is speci- 
fied. Also, if you don't supply a redraw routine, your window 
shouldn't have scroll bars. 

wPosition. wPosition (rectangle) defines the starting position 
and size of the window. The four word values are listed in the or- 
der MinY, MinX, MaxY, MaxX, and are in global coordinates. 

wPlane. wPlane (long value) indicates this window's prece- 
dence — in other words, how many windows are stacked on top of 
it. A long word of places the new window behind every other 
window on the desktop, A long word of SFFFFFFFF, which is also 
— 1. places the new window on top of all the others. 

wStorage. wStorage (long pointer) represents the address of 
additional storage for the window record. This value is always set 
to because Apple has not officially said what other values will 
mean in the future. 

The following are examples o( window records. Each corre- 
sponds to the NewWindow toolbox calls demonstrated earlier in 
this chapter. To add a window to your program, simply add the 
NewWindow call as shown above and have it reference a window 
record with the data you desire. The following window records are 
simple, standard window records. Later in this chapter, more excit- 
ing, splashy, and mind-boggling window records are used, 
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In machine language: 



WindowRec anop 






dc 


I'WRooEnd - Wlndo-wRec" 


;slze of parameter list 


do 


)%1101111110100000' 


;frame type 


dc 


14'Wtltle' 


;Tltle string pointer 


do 


14*0' 


^Reserved 


do 


18*0,0,0,0' 


;PoBltlon When Zoomed (0 = def) 


do 


I4'0' 


;Potnter to color table 


dc 


12*0,0 


;Conienta Vert/Horz Origin 


do 


ia-200,840' 


;Helght/Wldth of document 


dc 


IS'200.840* 


;Halght width for grow window 


dc 


12'4,16" 


;Vert/horz pixels for scroll 


dc 


12'40.160' 


;vert/b.orz pixels scroll page 


do 


14*0' 


;Value passed to Information 


dc 


I3'0' 


: Height of info oar 


do 


I4'0' 


; Window Definition 


do 


14-0' 


;Draw Info bar routine 


dc 


I4'0' 


;Draw Interior 


dc 


18'40.100,1S9,640- 


starting position and size 


do 


14-tFFFFPFFF" 


iStartlng plane 


dc 


14-0' 


;wlndow record 


WHscSnd anop 







A title string (called Wtitle in the program example) also needs 
to be defined. The title string is a Pascal string, which means it's 
preceded by a count byte. Below, the macro sir is used to define 
the title for this window; 

Wtitle str" Mr. Mondo " 

Note that the title is padded with spaces. If the spaces were re- 
moved, the title would appear jammed into the title bar. 

In C, global record structure can be used to create a window 
record as follows: 



ParamLlst 



WlndowReo = { 

Blzeof(windowRec), 

OidfaO. 

" \ p Mr. Mondo ". 

NULL. 

0. 0. 0, 0, 

NULL. 

0. 0, 

200, 640. 

200, 640. 



/' size of parameter Hat •/ 

/* frame type */ 

/* Pascal title string '/ 

/' refcon "/ 

/• Position When Zoomed (Q = deO 7 

/* Pointer to color table '/ 

/* Contents Vert/Horz Origin '/ 

/* Height/Width of document "/ 

/• height/width for grow window •/ 



.. 



157 



r>l »_^ n 








4. 16. 




/• vert/horz pixels for scroll '/ 


40. 160 




/' wrt/horz pixels scroll page ■/ 


NULL, 




/• information bar string '/ 


0. 




/' Height or Info bar 7 


NULL, 




/' Window Definition routine '/ 


NULL, 




/' Draw info bar routine •/ 


NULL, 




/■ Draw content routine '/ 


40. 100 


169. 640, /' Starting position and size ■/ 


-1L, 




/' starting plane ■/ 


NULL 

J; 




/' window record addrsss •/ 


In Pascal, your window record and its title string must first be 


declared in the VAR section of your program: 


VAB 






WlndowReo: 


lewWlndowParamBlk; 


TheTltle: 


String; 




The structure is then loaded with data at runtime (within a function 


or procedure) with the 


desired values: 


TheTltle := 'Mr- Mondo '; 




WITH WlndowReo DO BEGIN 




param_length 


= slzeof(NewWlndowParamBlk); 


wPrame 


= IdfaO; { frame type } 


wTitle 


= CTheTltle; j pointer to title string | 


wRefCon 


= nil 


{ refcon } 


SetRect 


(wZoom 


, 0. 0, 0. 0); 


wColor 


= nil 


; color table pointer } 


wYOrigln 


= 0; 


; content origin J 


wXOrlgln 


= 0; 




wDataH 


= 300 


{ document size ;■ 


wDataW 


- 640 




wMaxH 


= 200 


; | grow window size [ 


wMaxW 


= 640 




wScrollVer 


= 4; 


; scroll range J 


wScrollHor 


- 16; 




wPageVer 


= 40; 


! page range j 


wPageHor 


= 160 


, 


wlnfoRefCon 


= Longlnt(nll); [ Draw Info bar- routine } 


wlnfoHelght 


- 0; 


{ Height of info bar } 


wFrameDefProc 


= nil; 


j window Definition routine } 


wlnfoDefProc 


= nil; 


| Draw Info bar routine J 


wContDefProc 


= nil; 


{ Draw content routine | 
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setRect 
wPlane 

wStorage 

END; 



(wPoaltlon, 100, 40, 640, IBS); 

:= — 1: { starting plane ) 

:= nil: { window record address 



Once you've defined an acceptable window record, you can 
use it as a template for any other window applications you write. 
Customizing an existing window record is easier than building a 
new one each time from the ground up. The remaining sections in 
this chapter augment certain parameters of the window record, and 
help make your windows more exciting. 

Naming a Window 

About the only important thing to do when naming a window is to 
place spaces on either side of the title. The spaces provide adequate 
breathing room between the title and the rest of the title bar. 

The title of the window is specified in the window record, in 
the wTitle field: 

wTltle (long pointer) 

wTitle points to the address of a Pascal string that contains the 
window's title. In the previous window record example, the title of 
the window was listed as follows (in machine language): 

dc 14'wTltle' ;tlt!e string pointer 

The actual title is at the address wTitle; 

wTitle str My Window ' 

The str macro is used to create a Pascal string with a leading count 
byte for My Window. 

You can name a window anything. Or. if you use a long word 
of for the wTitle field of the window record, the window won't 
have a title. (This also holds true if you haven't specified a title bar 
for the window.) 

Most often, you'll want to use the name of the file you're 
working on as the title of the window. This involves a little byte- 
wise sleight of hand in machine language because of the way 
ProDOS stores a filename in memory. C and Pascal programmers 
can use standard string-handling functions which make this job a 
cinch. 



A ProDOS filename is stored as a Pascal string, and can be 
from 1 to 15 characters long (not including a prefix). The char- 
acters after the count byte make up the actual name of the file. 
Since a filename buffer can take up as many as 16 characters 
(the count byte plus the 1 5 letters), your programs should pro- 
vide at least that much space for that worst-case scenario, The 
string buffer should always be 16 characters long no matter 
how long the expected filename is. 



Suppose you've used the Standard Files tool set to return the 
name of a file on disk — either a text, picture, or some other file. 
When the file's name is returned, it is a maximum of 16 characters 
long, the first of which is a count byte. The filename can be as 
many as 15 characters long; if there are fewer characters, the re- 
maining characters are padded with nulls (zero bytes). 

The object for you, the programmer, is to examine the file- 
name string returned by the Standard Files tool set and make it 
suitable as the title of a window. Of course, you can't just use the 
filename returned by ProDOS. Instead, you must delicately extract 
the filename, being careful to add a space in front and a space be- 
hind for padding. And, don't forget to add 2 to the count byte. But 
the hard part is done for you, as explained below. 

In machine language, the following routine moves a ProDOS 
filename from its storage buffer to a window title storage buffer 
(the ProDOS filename is stored at location Fname; the window's ti- 
tle, at location wTitle): 



Pro2Wln 



LQNGA 


OFF 


L0NG1 


OFF 


eep 


130 


Ida 


Fname 


tax 




lnc 


A 


Inc 


A 


sta 


wTltle 


Ida 


120 


sta 


wTltle + 1 


sta 


wTltle + 2.x 



-,ProDOS-to-Wlndow Title 

,uae eight-bit registers 
;get the name's length In A 
;save a copy In X 
; Increase the length by 2 

,save It la the window's title 
;add a apace 

;to the beginning of the title 
.and one to the end 
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loop 



Ida 



one 

rep 

LONGA 

LGNG1 

rts 



Fname.x 

wTltle+l.x 

loop 

$30 

ON 

ON 



:read a character from filename 
;8tore filename in title buffer 
:work backwards to start of name 

;lf not zero, keep looping 

;baok to 16-bkt registers 



;and you're done 



This routine takes the filename from location Fname and 
moves it to the window's title location, wTitle, and adds one space 
on each end of the filename. The size of the wTitle buffer should 
be 18 characters, two more than the Fname buffer, so that it can 
hold the largest possible filename. 

First the routine reads the length of the filename; then it adds 
2 to that length {with two INC A instructions), one for each space. 
Then, before the file's name is transferred, a space is placed at the 
start and end of the window title. 

In the main program loop, the characters are moved from 
Fname to wTitle. Each character is taken from the right side of 
Fname, indexed by X, and it works to the left. When X reaches 0, 
the last character has been moved. This backwards copying method 
saves a few instructions that would have been needed if you were 
copying in a forward direction. 

In C, the logic follows that of machine language since C's 
string-handling functions aren't meant to be used with Pascal 
strings. The routine is as follows: 

Pro2Wln( ) 

! 



char x - Fname[Q]: 
wTltle[0] = x + 2; 
wTltl8[l] - wTltle[i + ZJ - 
for (: i. — — X) 
wTltl«[i + 1] = Pnams[i): 



f x = length of Manama 7 
f set wTKla'a new length "/ 
/• pad with spaces •/ 
f while x Is not zero. •/ 
/• copy the string •/ 



Far simpler, because of the compatible string format, the fol- 
lowing single statement can be used in Pascal: 

wTitle := CONCATC ', Fname. ' '): 

Feel free to include these routines in any of your programs that use 
a filename as the window's title. 
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Colorful Windows 

Windows on the Apple 1IGS come in several styles, from the plain, 
black-titled windows, to stylish and colorful windows that would 

make a Macintosh owner green with envy. 

The color of the window is set by the wColor parameter found 
in the window record: 

wColor (long pointer) 

wColor points to the address of a table containing the colors to be 
used in the window. If a long word of is specified, the Window 
Manager creates a black and white window with a solid black title 
bar. 

But you can change that. For example, the following could be 
included as the wColor parameter of a window record: 

dc 14'WColor' ;addres6 of color table 

The color table consists of five word-sized values, each of 
which describes a different color attribute of the window. The ac- 
tual colors are determined by the bit positions within each of the 
words. The five words are described in Table 9-4. 

Table 9-4. Color Table 

Color Word Sets the Color For 

FrameColor Window outline 

TitleColor Title, zoom, close boxes 

TBarColor Title pattern and background 

GrowColor Grow box 

InfoColor Info bar 

The bit positions are significant in each of these words. Gener- 
ally speaking, each word is split into groups of four bits (one nib- 
ble). These four bits can represent 16 values from (0000) - 15 
(1111). Each value then represents one color from the current pal- 
ette as set by QuickDraw 11. 
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FrameColor (Figure 9-2) sets the color of the window's outline, 
including the outline of the title bar and info bar. 

Figure 9-2. Meaning of Color Bits in FrameColor 

Bit 15 



Bit 



Outline Color 



Unused 



Always Zero 

The only bits of any significance here are at positions 4-7. 
Those values control the color of the window's frame. The other 
bits in this word should be set to 0. 

TitleColor (Figure 9-3) controls the color of the window's title 
(the name of the window), and the close and zoom buttons, as well 
as the colors o( the title bar and title when the window is inactive. 



Figure 9-3. Meaning of Color Bits in TitleColor 
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The inactive colors specified by TitleColor only appear when a 
window is inactive, or in the background. Otherwise, only bits 0-3 
are used when a window is first displayed to color the title, zoom, 
and close boxes. The inactive title bar color and inactive title color 
are best used when both values are opposites, such as 0000 for the 
first and 1111 for the second. When both are the same, the title of 
an inactive window appears all one color. 



Figure 9-4. Meaning of Color Bits in TBarColor 
Bit 15 



Bit 



Title Pattern Value 



Pattern Color Background 



In the TBarCoIor slot (Figure 9-4), the title pattern value is one 
of three values: (00000000) for solid, 1 (00000001) for dithered, 
or 2 (00000010) for barred— as on the Macintosh. 

The pattern color and background (Figure 9-4) set the fore- 
ground and background colors for whatever type of pattern is se- 
lected. For the solid title bar, only Pattern color (bits 4-7) are used. 
For a dithered or barred pattern, both values are used. 

In the GrowColor Slot (Figure 9-5), the alert frame, bits 12-15, 
are used when the type of window created is a dialog box and not 
an actual window. (Remember, the Window Manager is also re- 
sponsible for creating dialog boxes.) 

Figure 9-5. Meaning of Color Bits in GrowColor 
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Alert Frame 



Always Zero 



Grow Interior 
Inactive 



Grow Interior 
Active 



A special type of dialog box, the alert box, has a few outlines. 
The alert frame parameter above colors the alert box's middle out- 
line. The grow interior inactive parameter colors the inactive win- 
dow's grow box. The grow interior active parameter colors the 
active window's grow box. 

As with GrowColor, bits 12-15 of InfoColor (Figure 9-6) deter- 
mine the color of an alert box. This time the parameter affects the 
inside outline's color. 

Figure 9-6. Meaning of Color Bits in InfoColor 
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Interior Color Inactive Unused 



Alert Frame Always Zero 

The only other significant bits are 4-7, which control the inte- 
rior color of the window when it's inactive. 

A sample color table would be as follows. In machine lan- 
guage, the percent sign is used to indicate a bit value description of 
the word. The following color table creates a typical Macintosh- 
style window using only black and white color values. 



_ 
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WColor do l'%OO0O000000O0Q0OO' ;frame color 

do I'ftOOOQllllOOOOOOOO' ;Plt]9 Color 

do I'fcOOOCWlOOOOOllir ;Tltle Bar Color 

do rfcOOOOOOOOllllOOOQ" ;Grow Box Color 

dc rftooooooociinoQOO' ;info Bar Color 

In C, a sample color table declaration would be 



WlndColor 



wColor = 

0x0000, 
OlOfOO, 
0xO30f, 

oxooro. 

OxOOfO \\ 



l' frame color */ 

/' title color •/ 

/' title bar color •/ 

/* grow box color ■/ 

/• info bar color •/ 



And in Pascal {wColor is defined as a WindowColorTbl type): 



WITH WColor DO BEGIN 

FrameColor := 40000 

TltleColor ;= IQFOO 

TBarColor := I030F 

Qro wColor := I00F0 

InfoColor : = I00F0 
END; 

Using these premanufactured structures, you'll find it easy to 
experiment until you create the right window for your needs. 

Window Contents 

What good is a window unless you can put something into it? Not 
much. Putting data into a window isn't that difficult; it just requires 
that you know which buttons to push. 

The contents of a window are drawn by a routine indicated in 
the window record. The wContDefProc parameter contains the 
long address of a routine that draws the window's contents: 

wContDefProc (long pointer) 

The routine, if written in machine language, should end in an RTL 
instruction. Functions and procedures in C and Pascal always end 
in RTLs. The wContDefProc routine draws the contents of the win- 
dow, then exits. There are no input or output parameters, nor do 
you need to do any extensive graphics tweaking. 
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The wContDefProc routine is called by the TaskMaster to up- 
date the window's contents — for example, when the window is 
scrolled or its size is changed. When you're using graphics, the 
window's port will be the current GrafPort. 

If wContDefProc is a long- word of 0, then the window will be 
blank, and scrolling about in the window will erase the window's 
data. This is why windows without a wContDefProc routine should 
not have scroll bars. 

The following are two examples of the wContDefProc param- 
eter in a window record. The first is an empty field, meaning no 
procedure is defined. The second is the address of a procedure to 
draw the contents of a window. 

In machine language: 



dc 14'0' 



:no update routine 



dc 14'WContent' ;addreB8 of update routine 

In C: 
WlndowRec.wContDefProc = NULL; /• no update routine •/ 

or 

WlndowRec.wContDefProc = WContent: f name of function */ 

In Pascal: 

WkndowRec.wContDefProo := nil; { no update routine } 

or 

WlndowRec.wContDefProc := ewContent; [ address of procedure } 

See the MONDO program example in the next section for a 
wContDefProc routine that displays a string in a window. When 
designing your own update routines, remember that the actual size 
of the window's port is set by the window record when the win- 
dow is created. 

Also, for some reason, having a wContDefProc routine that is 
just an RTL instruction (or a null routine or procedure in C or Pas- 
cal) doesn't seem to work. It causes the machine to crash. Appar- 
ently some window access or graphics interaction is required by the 
routine. This could be because of the versions of tool sets that the 
IlGS uses at the time of this writing. 
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The MONDO Window Program 

Below is the program MONDO as written in machine language, C, 
and Pascal. It uses the program MODEL (introduced earlier in this 
book) as a base upon which to work. To run the MONDO pro- 
gram, you'll need to copy and rename the MODEL program and 
merge in the following modifications. The program is only altered a 
little, so there need not be much retyping. 

MONDO adds two windows to the MODEL program and per- 
forms some interesting trickery with pull-down menus. The 
windowing routines are used to open and close two separate win- 
dows. An extra routine has been added to hide or show the first 
window and to demonstrate how easy the Window Manager's 
functions are to use. 

When you begin experimenting with this program, change the 
Show/Hide menu option to some other Window Manager function 
{SelectWindow, BringToFront, SendBehind, HiliteWindow, or a 
number of others. 

MONDO also demonstrates some interesting Menu Manager 
functions. For example, when a window is open, its corresponding 
open menu item is dimmed. When the window is closed, its close 
menu item is dimmed. This is done with two Menu Manager calls, 
EnableMItem and DisableMItem. Additionally, when the first win- 
dow is hidden, the Hide menu item changes to Show. This is ac- 
complished with the SetMItemName function and can be seen in 
the code samples below. 

Another interesting thing to note is how the first window 
makes use of a custom color table and the second window uses a 
default color table. Also, note how the wRefCon value is used to 
identify each window. Because wRefCon's value can be anything 
you want, MONDO uses it to identify which window is being 
closed in order to update (dim or enable) the associated menu item. 
This is done with the GetWRefCon function in the CloseW proce- 
dure in the following source code Listings. 

As usual, feel free to modify this program or use its routines in 
your own applications. As a special project, try to fix the error that 
occurs when an invisible window is closed and the Show menu 
item is not changed back to Hide. 



rogram 9-1. Machine Language Source for MONDO-ASM 
• 

HONDO. ASH ■ 

Sample Desktop Application in APV Assembler {1.05 • 

Windowing Routines » 



To create the Hondo. Macros macro tile, use this APW shell conmand: 
; I macgen roondo.asn) monoo. macros 2/amclude/ral6= 

ABSADDR ON 

KEEP Hondo 

MCOPY Hondo. Hacroa 



Global Equates 



Toolbox gequ 
TRUE gequ 
FALSE gequ 
Page gequ 
fflOpenl gequ 
inHidel gequ 
mClosel gequ 
m0pen2 gequ 
mCloseZ gequ 

I •NOTE* 
; «N0TE» 

HodelA START 
phk 
plb 
or l 



(Primary tool dispatcher 

sTrue value 

(False value 

[The size of a page (256 bytes) 



SelOOOQ 

S8000 

»0000 

9100 

25? 

258 

2S9 

260 

261 



From this point on. copy the source from 
the original MODEL. ASH APW program... 



; »N0TE« 
: «N0TEi 



jor 
JXJIT 



;Hake the data Bank... 
(...the current code bank 
Main (branch over Junctions to Nam 

Et cetera, on down to the end of the 'Main' routine 
as fol lows: 

ShutDevmTools (Shut down all tools started 

Qparms (Exit this program through ProDOS 16 



i »N0TEf Then add what follows after this point. 

; "NOTE* It augments and replaces the rest of the HodelA 

; iNGTE* source code: 



Window Routines 



Openl pea so 000 
pea SO 000 

push long HVindRect 
.NewWindow 



jsr ErrChk 

pul I long WmdPtri 



: long result space 



; first window record 
;open it 



(check for errors 
;get pointer II 



_ 
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pea mOpenl 


sthis menu item number 




_0J38OI«f11t«H 


■ aim it 




pea mHidel 


; enable these two 




.EnaeleHItem 






pea mClosel 






_EnableHItem 






rts 






hi deb it dc i2'0' 


tzero ■ window is visible 




Hidel Ida hidebit 






oeq Hidelt 






Showlt pushlong WjnOPtrl 


ishow the window 




_ShouVlndou 






push long OTiHide 


; change the name back 




pea mttidei 






_SetHItemName 






Ida MO 






aid hidebit 






rts 






Hidelt pushlong VindPtrl 


;hide this window 




_HideWinoou 


:hide jt. no errors 




push long tmShow 


;change menu item name 




pea raH i ae 1 


•this j tern number 




_SetMItemNaitie 


; change the name 




Ida MFFFF 


;change status byte 




sta hidebit 






rts 






0pen2 pea *0000 


; 1 ong resu 1 t space 




pea aOOOO 






push long «WinaRec2 


: second window record 




_Nevta> inflow 


;open that wmdou 




jsr ErrChk 






pull long WinaPtr2 


■get second windows pointer 




pea m0pen2 


mow. dim this menu 




_DisableMlteni 






pea mClose2 


;and enable this item 




_EnabieMltem 






rta 






Closel pushlong WinoPtrl 


:close this window 




_CioseWindow 
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pea mOpenl 
_ En abler! It em 

pea raH i del 
.DiwbleKJ ten 

pea mClosel 
_DisableMl tern 
rts 
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:thi3 menu item number 
:Enable this again 



;disable these two 



Close2 pushlong WlndPtr2 
_CIoseWindow 



pea m0pen2 
_EnableHItem 

pea mClose2 

.DisableKItem 

rts 



iclose wi ndow two 
: re-enable this item 



: close whichever window was clicked 



CloseW pea 90 000 
pea 90000 
pushlong TaskData 

_urlVKct<Jun 

pla 
Pit 

cmp «l 

beq Closel 
bra Close2 



WContent pea 90028 
pea 90020 
_MoveTo 



: long result space 

;get the winoow's pointer from Taskdata. 

|gtt Uir vininv 3 wKcCCun Vfllyc 

:get low order word into a 
stoss away high order word in x 
iif 1, then it's window l 
:so close wi ndow 1 
;else. cloae window 2 



Horizontal pointer loc. 
Vertical pointer loc. 
(QuickDraw) 



PushLong "StringO 
.DrawCString 



rt I ; long return 

StrmgO dc c'Tnis is a string inside the window." , ilC 



Variable Storage 



User ID 


ds 


2 


flemlD 


09 


2 


DPBase 


ds 


2 


CFlag 


dc 


i 



'FALSE' 



;0ur User ID 

:Memory User ID (made from User ID> 

;Used by DP buffer manager 

:&oolean; Quit flag (starts out as false! 



* - "««"H[ 

« Startup/Shutdown Tool Lisi ■ 



170 














Tool ist dc l'<TcolstE-To0ll3t-l>/4' ;Tool count 


dc I'l.O' • Tool Locator 


dc i '2,0' i Memory Manager 


ac 1*3,0* t Mlac Tools 


dc 1*4,0' : QuickDraw 11 


dc t '6,0' | Event Manager 


dc i'H.0* j window Manager 


dc i"16.0' i Control Manager 


dc riS.O' ; Henu Manager 
dc i'5.0- ; Desk Manager 
ToolstE anop 


« Pull Down Menu Structures « 


MenuTCI oc J CI1enTblE-MenuTbl-l >/2' -Menu count 


ac I'Henur -Apple 


dc I'HenuZ' i Window 


dc i'Benu3' ;Quit 


HenTblE anop 


Kemii etc c*>>3\XNI'.ll*Q' :Apple 


dc C — About This Program.- .\N256* ,ll'0* 


dc c' — MV.Il'O* 


ac c>* 


Menu? ac c*» Window \N2\irO' -Window 
ac C'--0pen Windoul\N257' .110' 


ac c--Hiae Winaou)\DN258'.U'C<" 


Oc c -Close Vinaowi\DVN259* , 1 1 * 0* 


dc C --Open Wlndou2\N26Q* .110' 


ac c --Close Winaow2\DN26l' , il- 


ac o* 


MenuJ ac c'>> Ouit \N3'.il'Q' ;0uit 


ac c--t3uit\N262«0q.i I'D' 


ac c * > 


mShow str ' Show Windowl ' -changing menu items 


mHioe str Hide Window!' 


• Menu Hem Dispatch Addresses « 


MTaCle ac r About' ;256/About (Apple Menu) 


ac i-Opent' ;25?/0pen window i {Window Menu) 


ac I'Hidel' s 258/ Hi* window 1 


ac I'Cloael' ;259/Close window 1 


ac i Qpen2 ;260/0pen window 2 


OC l'Close2 :261/Close window 2 


ac I'fXut ;262/Qult (File NenuJ 


# The Event Record * 


EventRec anop jEvent Record used by TaskMaster 


EVhat as 2 ;What 


1 



















uIlaUltTl 33 




£rtsg 




ds 4 


; Message 




EWhen 




ds 4 


sWhen 




EWhere 




os 4 


;Where 




EMods 




03 2 


iModtf lers 




Task Data 




as 4 


i Task Data 




TaskHask 




dc i4'»lfff 


■Task Mask 


» Window Data * 




WlndPtrl 


ds 1 


:Wi ndow pointer 




Wltltle 


str 


• Mr. Mondo One " 






WiCtable 


dc 


10000000000000000* 


: frame color 






dc 


'V0000t 11 100000000' 


;Title Color 






dc 


'MOOOOCSOOOQOllll* 


;Tl t le Bar Color 






dc 


■wjoooooooimoaoo' 


;Grow Box Color 






dc 


'woooooooimoooo' 


! Info Bar Color 




VindRvcl 


anop 








dc 


I'WRlend-WindRecl' 


sslze of parameter 1 1st 






dc 


k**Lioiiinioiooooo* 


; frame type 






dc 


l4'Wltlt1e* 


gtitle 






dc 


14*1' 


:Used for window number here 






de 


120.0.0.0' 


:Position When Zoomed 0»def 






ac 


14'WictaBle* 


■Pointer to color table 






de 


i2'0,0' 


;Contents Vert/Horz Origin 






dc 


12' 180. 640* 


iHelght/Vidth of document 






dc 


12' 180,640* 


-height/width for grow window 






dc 


.2-4. 16' 


;veri/horz pixels for scroll 






OC 


i2 40,160' 


;vert/horz pixels scroll page 






dc 


14*0' 


■Value passed to information draw 






dc 


12*0' 


iHeight of info bar 






dc 


14*0' 


;Window Definition 






dc 


I4"0' 


;Draw info bar routine 






oc 


i4'WContent* 


:Draw Interior 






dc 


i '40.100.159,540' 


iStarting position and size 






dc 


i4'*FFFFFFFF' 


^starting plane 






dc 


i-l'O- 


iWindow Record 




WRlend 


anop 






WindPtr2 ds 


4 


■Window pointer 




V2title 


str 


" Mr. Hondo Two " 






WmdRec2 anop 








dc 


l'WR2end-WindJ?ec2' 


;sne of parameter list 






dc 


I'HllOlllMLOlOOOOO 


■frame type 






dc 


l4'W2tltle' 


•title 






dc 


i4'2' 


iUsed for window number here 






OC 


i2'0, 0.0.0' 


iPosltlon When Zoomea 0=oef 






dc 


14*0" 


mo color table 






dc 


12*0.0* 


sContents Vert/Horz Origin 






dc 


12' 180. 640' 


:Height/Vidth of document 






dc 


i2* 180.640* 


:height/width for grow window 






dc 


i2'4.16' 


ivert/hon pixels for scroll 






dc 


i2'40.160* 


jvert/horz pixels scroll page 






dc 


14*0' 


; Value passed to information draw 






dc 


12*0* 


t Height of info bar 






OC 


14'0' 


;Window Definition 
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»'P2er CI 



dc I4'0' 
ac i4'0' 

dc ; SO, 120. 169. 560- 
dc I4'»FFFFFFFF 
dc i4'0 J 

4D0P 



Hi see I laneous Data 



:0raw info Oar routine 
;Dr«u Interior (none) 
iStartmg position ana size 
istarttng plane 
iWmdow Record 



GrafPortPtr VindPtrl. 
WindPtrSs 



WindColor 



ViCtabie = < 
0x0000. 
OxQtOQ, 
Ox 020 f . 

0x00(0, 
QxOOfO 



/» Window port pointers *> 



r* frame color *t 
/* title color •/ 

/• title oar color •/ 
/. grow box color «/ 
/* mlo bar color */ 



Moment dc 



QParms dc 
dc 



c'One Moment., .'.il'O' 



14'*' 

j'*0000' 



;ProDOS 16 Quit Code parameters 



mt WContentO: 

ParamList WmdRecl ■ < 



Program 9-2. C Language Source for MONDO.C 

• HONDO. c » 

• Sample Desktop Application in APW C c 1 .0 J • 
• _ „ 

'• "NOTE" This is not a complete program. Merge parts of 
thlfl listing with the HODEL.C program from 
Chapter Six. Insert portions from HODEL.C where 
indicated. •' 

/« uncluae directives -- insert from HODEL.C «/ 

■define mAbout 256 /« Henu item Ills «/ 

laetine mGpenl 257 

•denne aiHidel 258 

•aetinc roClosei 259 

naetine m0pen2 260 

•detme mClose2 261 

•aenne mUiit 2$£ 



ParamList 



Global Variables 



WmTasxRec 


EventRec: 


Wora 


Event. 




User ID, 




HemlD. 




OFiagr 


Wora 


Tcolistl 1 




3. 




14, a. 




IS. 0. 




16. 



char 



•DPBase; 



/•» Event Record Structure •/ 

/» Event code */ 

ft Our User ID */ 

/* Memory Management ID #/ 

/» Boolean: Ouit flag */ 



/■ Tool count *-/ 
/» Vmdou Manager */ 
/* Henu Manager »/ 
/» Control Manager •/ 



/* Direct Page Case pointer */ 



)1 



3i«of«WmdRecl), 

OxdfaQ, 

■\p Hr. Hondo One ' 

IL, 

0. 0. 0. 0. 

aviCtable. 

0. 0, 

180. 64D. 

leo, 640. 

4. 16. 

40. 160, 

NULL. 0. 

NULL. 

NULL. 

VContent, 

40, 100, 159. 540. 

-IL. 

NULL 



/* size ot parameter list */ 
/• frame type */ 
,/• window title «/ 
/» gsea for window number */ 
/» position when loomed «/ 
/» color table »/ 
/* content vert/horz origin •/ 
/• height/wiath ol document */ 
/. height/width for grow window «/ 
/« vert/horz pixels for scroll »/ 
/• vert/horz pixels lor page t/ 
/■ no info car •/ 
/» wmoow definition •/ 
/» draw info Mr •/ 
/« draw inter lor •/ 
/• position / size •/ 
/* plane ■/ 
•« window record address »/ 



UmaRec2 ■ ( 

sueof<WlndRec2). 

OxdfaO. 

•\P Hr. HonOo Two " 

2L. 

0. 0, 0, 0, 

NULL, 

0. 0. 

180, 640, 

180. 640, 

4, 16. 

40. 160. 

NULL, 0, 

NULL, 

NULL. 

NULL. 

50. 120. 169. 560. 

-IL. 

NULL 



/• size of parameter list ■/ 

/» frame type •/ 

./• window title ■/ 
/* used for window number */ 
/« position when zoomed ■/ 
/» color table */ 
/» content vert/horz origin */ 
/» height/width of document •/ 
/» hei*t/width for grow wmoow »/ 
/» vert/horz pixels for scroll »/ 
/« vert/horz pixels for page «/ 
/» no info bar »/ 
/« window definition »/ 
/• draw info t>ar */ 
/» draw interior »/ 
/• position / size */ 
/« plane »/ 
/» window record address •/ 



Boolean hi debit = FALSE; 



_ 
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/• ErrChto 

t* GetDPCJ 

/# StartUpToolsO 
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-- insert from HODEL.C " 
-- insert from HODEL.C •/ 
-- insert from HODEL.C »/ 
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/„ 1 

■ Prepare Desktop and Menus • 
a . « 1/ 

PrepDeskTopi 3 
< 

Static char »Appl*rt*nu[ ) = t 

■»8voati», 

"—About This Program- . a\N256" , 

■-—WD', 

■>■ 

>: 

static char »WindowMenu! ) - « 
•» Window \\N2", 
•—Open Windowl\\N257". 
•--Hifle Windovl\\DN258'. 
"—Close Winoowl\vDVM259", 
•—Open Window2\\N260' 1 . 

• - -C I ose w i noow2\\DN26 1 ■ , 

* >■ 
>: 

static char »OuitMenuM ■ C 

" » Qu it \\N3" . 

"~0uitv.N262«0q\ 

•>" 
>: 

RefreshDesletopCnil); /i Display Desktop •/ 

ImtCursort): /* Show mouse cursor */ 

InsertMenu<Newrlenu!9jiitl1enut03). 0); /» Install menus »/ 
lnsertMenu<NeuHenu(Wi ndouHenu(OI) , >; 
Insert«enu<NeurleiHiCApple»frnu[Q)}. 0); 

FixAppleMenu(l); ./» Display menu bar »/ 

FixHenuBart is 
DrawMeriuBart 3 s 

5 

• Apple Menu; About « 
» 1/ 

About < 3 
( 

/• Does nothing < for now3 »/ 
3 

/« , 

* Window Content Procedure » 
, — 1/ 

"Content O 

< 

KoveTo<0x2e. 0x203: 

DrauCStrmgt'ThJs is a string inside the window," >; 
} 



* Window Menu: Openl 



1 
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Openl (> 
t 



WindPirl ■ HewWindow<S.WindPecl3: 

DisaDlel1ItemCBiCipeni3: 

Enab I eHl t emtmH i de I > ; 

EnableMJ temlmCl osel 3 : 



* Window Menu: Hidel 



/* open (irst window */ 
/« disable openl item */ 
/» enable these two..- »/ 



HioelC > 
( 

it 



chideDit) i 
ShowW « n dow< W i ndPt r 1 3 : 
SetnitemHaraefVpHide Windowl" 
hiaebit ■ FALSE: 

3 else ( 

HideWmdow<WindPtrl >: 
SetH!temName<"\pShow Windowl" 
hidebit = TRUE: 

3 



/« — 

« Window Menu: QpenZ 



0pen2« ) 



WlndPtr2 ■ NewWindow(fcWindRec2>; 
DisableMItemtmOpen23 : 

EnableHItera<.mClose23; 



* Window Menu: Closel 



/* open second window -/ 
/« disable open2 item «/ 
/• enable close2 Item */ 



CloseWindowtWindP trl3: 
EnaoleMItemCm0penl3 ; 
DisableBItem<mH:dei >: 
DisableMltemlmClosel I: 



t Window Menu'- Close2 



Cl0»2<) 
( 

CloseWinoowcWjndPtr2>: 

EnableHI temCmOpen23 : 



/* close this window •/ 
/» enable openl Item *t 
/# disable these two.. 



/« close window 2 »/ 
/» enable open2 Item •/ 
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j 



Disa0leMltera<mClose2}: 



C I oseVK j 
( 

ll CC*CVfRe(Con<EvfntRec.wniTasfcDat4} 

CloselC); 

Close2c): 
) 



/• disable cloa«2 item ■/ 

/# close whichever window was clicked #/ 
I) 



Do Menu Selection 



-./ 



DoHenuO 
( 

switch <EvencRee.wmTaskDataJ ( 



case mADout : 


About ( > : 


break : 


case mOpen] i 


OpenHJ; 


breaks 


case mH J del : 


HideH); 


t r eak ; 


case mClosei i 


CloselC}; 


break ; 


case m0pen2: 


0pen2< J; 


break ; 


case mClose2: 


Close2C3i 


break ; 


case mOu 1 t : 
) 


OF lag - TRUE; 


break : 



HI I IteHenuCFALSE, EventRec.vmTaskData»t6>; 
3 

/* ShutDownToolsO -- insert from MODEL, C */ 

/•— - # 

* Main # 



main< > 

i 



StartUpToolsCJ: 

PrepDeskTopI); 



OF lag = FALSE; 
EventBec.wmTasicMask 



-•/ 



/* Start toolsets ■/ 

/* Prepare desktop ana menus •/ 



QxOOOOKJf; 



whi le CfOFIagJ ( 

Event = TaskWasterCQxffff. 8,EventRee>; 
switch (Event) ( 



case wlnHenu&ar: 
case winGoAway; 



DoMenuO i 

CloseVO; 



break : 
break ; 



Program 9-3. Pascal Source for MONDO.PAS 

l . . 

• HONDO. PAS 

. Desktop Application in THL Pascal Cvl.QU 



{ "NOTE" Tms is not a complete program- Merge sections 
iron the MODEL. PAS program in Chapter Six 
where indicated. ) 

PROGRAM HondoP: 

USES QDlntF. 
GSIntF. 

HiscTools; 



CONST 



mAbout » 256; 
mOpenl = 257; 
mKioel = 258; 
ffiClosel = 259! 
mOpen2 = 260; 
n»Close2 ■ 26l : 
mOuit ■ 262; 



( Menu item IDs ) 



Global Variables 



-* > 



VAR EventRec: 
Events 

UsertD: 
MemID: 
DP Base: 
QFlag; 



EventRecord: I Taskmaster Structure ) 

Integer,' < Event code ) 

Integer; < Our User ID > 

Integer! ( Memory allocation ID > 

Integer; < Direct Page base pointer ) 

Boolean; < Boolean: Quit flag ) 

(Pull down menu strings > 



AppleMenu: String; 

VjnoowHenu: String; 

OuitMenu: String; 

VmdPtrl: VinoowPtr; 

WindPtr2: VinoowPtr: 

WLTitle: String; 

VKTitle! Stringi 

WlCtable: WindowColorTbl ; 



c Window port pointers ) 



W i ndfiec I : 
«indRec2; 



NevW l n dovPar amB I k ; 

NewM i n dowPa r amB I k ; 



ShutDownToolsCJ; 
exitcOl: 



/« Shutdown al I tools started •/ 



C PROCEDURE ErrChk -- insert Jrom MODEL, PAS I 

( FUNCTION GetD -- insert from MODEL. PAS ) 

< PROCEDURE StarlUpTools -- insert trcm MODEL. PAS > 



• Prepare Desktop and Menus » 
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PROCEDURE PrepDesKTopi 
VAR 

Height: Integer; 



C Menu bar heigth {unuaed> ) 



BEGIN 

AppleHenu :» C0NCATC'>>9\XN1\Q' , 

'--About This Program. ..\N256\0' , 

• — \D\CT . 

•>')s 

WinoowMenu :»CONCATt'>> Window \N2\Q'. 

"—Open Windowl\N257\0', 
'--Hide Windawl\DN258\Q'. 
'—Close Winaowl\DVN2SO\0' , 
'--Open Wlndow2\N260\0'. 
•--Close Wmdow2\DN26lMr. 



Qoitltenu :« CONCAT('» Quit \N3\0' . 
•--Oult\H262«Gq\0'. 
>'>! 

RefreshCNl!): 
En i (Cursor i 



( Display Desktop > 
( Show mouse cursor ) 



InsertHenuCNewKenuOQui tHenuIll). 0>; < Install menus ) 
InsertWenycNewHenu«8VinoowMenu[l)J. 0); 
In3ertHenuCNewHenii<8AppleMenuI 13). Q): 



FixAppleHenui I): 
Height :» FlxHenuBar: 

DrawHenu&ar: 



( Display menu bar ) 



END; 



< » 

• Apple Menu: Aoout 



PROCEDURE About; 
BEGIN 

c Does nouung (for now) > 
END: 



( »- 



Window Content Procedure ■ 
. , j 



PROCEDURE WContent: 
BEGIN 

MoveTo<*28. »20>; 

DrawStringcThts is a string msiae the window.'): 
END; 



• Wmoow rtenu: Openl 



PROCEDURE Openl: 
BEGIN 

WITitle :« • Mr. Hondo One ' 
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WITH WiCtaole DO 


BEGIN 






FrameColor 


- *Q0QQ 








TitleColor 


= »0f00 








TBarColor 


= *020i 








GrowColor 


■ soofO 








InfoColor 


• SOQfO 








END; 








WITH WmdRecl DO 


BEGIN 






par4m_ length 


:■ SIZEOFCNewWindowParamBllOi 


wFrame 


:= »dfaO; 




C frame type > 


wTitle 


:= vWlTltle; 




( window title ) 


wRefCon 


:= 1; 




( window number > 


SetRect 


("Zoom. 0. 


, o, o): 


( position when zoomed ) 


wcolor 


!■ awtCUDle 


i 


( color taole 3 


wYOrigm 


I- 0; 




( content vert origin ) 


uXOngm 


;- 0; 




( content hori origin ) 


wDataH 


:- 160: 




( height of document > 


wDitaV 


l- 640s 




( width of document J 


wHaxH 


s- ieo; 




t height of grow window ) 


w«axW 


(■ 640; 




< width of grow window ) 


wScrol IVer 


:= 4! 




< vert pixels; scrol 1 ) 


wSerol l Hor 


:■ 16: 




< horz pixels; scrol 1 ) 


wPageVer 


:= 40; 




{ vert pixels for page ) 


wPageHor 


:= 160: 




i horz pixels for page ) 


wlnfoRefCon 


:« LonglntCn 


Ll)i 


i no info bar ) 


wlnfoHeight 


:- 0; 




i no Info bar ) 


wFrameDefProe = =■ nils 




C window definition > 


wlnfoDefProc 


:= nil: 




( draw info bar ) 


vContDefPfOC 


:» QWContent 


; 


t draw interior > 


Set Reel 


JuPosition. 


100. 40 


540. 15°>: 


wPlane 


:= -l: 




C plane 1 


"Storage 


:- ni It 




( window record address ) 


END; 








WindPtrl :» New* 


indowtWindRecn 


< open first window ) 


Disa.bietUtem(mQpen|>; 


< disable openl item ) 


EnablenltemtmHidel >: 




< enable these two. . , ) 


EnableHItem<mClosel )| 






END; 








* Window Menu 


; Hide! 


» 




PROCEDURE Hi del 




BEGIN 








IF hidebit THEN BEGIN 






ShowWindowCWindPtrl>: 






Setr1ItemName< Hide Vindowl' . mHidel); 


hidebit 


:■ FALSE; 






END 








ELSE BEGIN 








HideWindowcWlncFtri); 






SetHltemNameC'Show Wmdowl' , fflHldel>; 


hidebit 


:= TRUE: 






END: 








END: 
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' 







dows — - 




win 




* Window Menu: 0pen2 » 






PROCEDURE 0fen2; 




BEGIN 






W2Title : = ' Mr. Hondo Two '; 






WITH Wincffiec2 DO BEGIN 






par am_ length i- SIZEOFCNewWi 


ndowParamBlk ) ■ 




vFrame := SdfaD; 


< frame type > 




wTltle :*> 9W2Title; 


i window title } 




wRefCon :- 2; 


< window number ) 




detRect cwzoom. o, 0. a 


, CI); < position when zoomed > 




wColor :■ nils 


< color table ) 




wYOrigm :■ 0s 


< content vert origin ) 




wXOrigm :■ 0; 


< content horz origin ) 




vDdtaH la 190; 


( height of document ) 




wDataW := 640; 


< width of document ) 




wMaxH :• 190; 


( height of grow window > 




wMaxW : = 600; 


( width of grow window ) 




wScroi iver ;= 4; 


( vert pixels: serol 1 ) 




wScrol IHor != I6j 


( horz pixels: scroll ) 




vPageVer -.= 40; 


( vert pixels for page ) 




wPageHor :» 160; 


( hon pixels for page ) 




wlrrfoRefCon r* LongtnUnil) 


( no info bar > 




ulnfoHeight ; = 0: 


c no info oar ) 




uFrameDefProc := nil ; 


( window definition ) 




wlnfoDefProc .» ml ; 


( draw info car ) 




wContDefProc :• nil ; 


( draw interior > 




SetRect (wPoattion, 120 


50. 560, I69>: 




wPlane :» -] ; 


< plane ) 




wS tor age :« nil; 
END; 


( window record address ) 




VitiCPtrZ :■ NewWindow<Vir>dJ?ee2><- 


c open second window ) 




DisaoleM.lteni<[ii0pen2>: 


{ disable open2 item ) 




EnableMItem{mClose2>: 
END; 


( enable close2 item ) 




• Vinaow flenu: Closel • 












PROCEDURE Closel; 






BEGIN 






CloseWmaowcWmdPtrl): 


< close this window > 




EnableMrtemCmQpenl 3 ; 


< enable open l i tern > 




DlsableHItemJmHldel): 


« aisable these two... > 




DisaBleMIiwntmCloMl>; 






END; 












» window Menu: Closed ■ 






PROCEDURE CI 03*2; 




BEGIN 






CloseWindow<VindPtr2); 


C close window 2 ) 




EnableMtem<m0pen2>; 


f enable open2 item J 




DisableHItem<niClose2J; 
END: 


C disable close2 item > 
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( close whichever window was clicked ) 



PROCEDURE CloseW; 
BEGIN 

IF GetVBefConCWmdowPtrCEventRecTaskData)) * 1 THEN 

Closel 
ELSE 

Close2: 
END; 



C •-- 



Do Henu Selection 



-■ > 



PROCEDURE DoMenu; 
BEGIN 

CASE LoWord<EventRec.TaskData) OF 
mAbout: About; 



mOpenl i 

mHidei: 

mClosel: 

mOpen2: 

mCIose2: 

mOui t: 



Openl ; 
Hidel: 
Closel; 

Open 2; 

Close2: 

OFlag :- TRUE; 



END; 

HiliteMenu<FALSE. KiVordCEventRec.TaskData)) : 



END: 

( PROCEDURE ShutDownToolS 

< •— 

» Main 



BEGIN 

StartUpTools; 

Prep DeskTop i 

OFlag := FALSE; 
hideblt ;= FALSE; 
Even tRec. Task Mask 



insert from MODEL. PAS ) 



< Start toolsets ) 

( Prepare desktop and menus i 



sOOOOifffi 



REPEAT 

Event i- TaskHastert-l. EventReo): 
CASE Event OF 

wlnHenuBar: DoMenu; 
wlnGoAway: CloseW; 
END: 
UNTIL OFlag; 



ShutDownTools 



I Shutdown all tools started ) 



END. 









_ 



Windows — 

Chapter Summary 

The following tool set functions were referenced in this chapter. 

Function: $020£ 

Name: WindStartUp 

Starts the Window Manager 
Push: UserlD (W) 
Pull: Nothing 
Errors; None 

Function: $030E 

Name: WindShutDown 

Shuts down the Window Manager 
Push: Nothing 
Pull: Nothing 
Errors: None 
Function: $090E 

Name: NewWindow 

Creates a window on the DeskTop 
Push: Result Space (L); Window Record (L) 
Pull: Window Pointer (L) 
Errors: S0E01, S0E02 

Function: $0B0E 

Name: CloseWindow 

Closes a window, removing it from the DeskTop 
Push: Window Pointer (L) 
Pull: Nothing 
Errors: None 



Function: 


$120E 


Name: 


HtdeWindow Hides a window, making it invisible 


Push: 


Window Pointer (L) 


Pull: 


Nothing 


Errors: 


None 


Function: 


$130E 


Name: 


Show Window 




Displays a previously hidden window 


Push: 


Window Pointer (L) 


Pull: 


Nothing 


Errors: 


None 
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Function: S1D0E 
Name: TaskMaster 

Tracks mouse, menu, and window events 
Push: Result Space (W); Event Mask (W); Event Record (L) 
Pun: TaskCode(W) 
Errors: S0EO3 

Function: 

Name: 



Push 
Pull 

Errors 



S290E 

GetWRefCon 

Returns the value of a window wRefCon parameter 

Result Space (L); Window Pointer (L) 

Window's wRefCon (L) 

None 



Menu Item Calls 
Function: $300F 

Name: EnableMItem 

Enables a dimmed menu item 
Push: Menu Item's ItemNum (W) 
Pull: Nothing 
Errors: None 

Function: £31 OF 

Name: DisableMItem 

Dims, or disables, a menu item 
Push: Menu Item's ItemNum (W) 

Pull: Nothing 
Errors: None 



Function 


S3A0F 




Name 


SetMltemName 






Changes the name of a menu 


item 


Push 


Pascal String (L); Menu Item' 


, ItemNum (W) 


Pull 


Nothing 




Errors 


None 




QuickDraw II Calls 




Function 


S3A04 




Name 


Move To 






Moves the graphics pen to a 


specific coordinate 


Push 


Horz Position (W); Vert Position (W) 


Pull 


Nothing 




Errors 


None 
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Funclion: SA604 

Name: DrawCString 

Displays a C string in graphics mode 
Push: C String (L) 
Pull: Nothing 
Errors; None 






_ 
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Dialog Boxes 

Dialog boxes offer you a chance 
to communicate with the per- 
son using your program. Like 
the buttons and viewing win- 
dow on the front of an auto- 
matic teller machine, dialog 
boxes are the most easily un- 
derstood ways for a computer 
to display information and ob- 
tain input, particularly when 
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compared to the old-fashioned Yes/No prompts and dreary com- 
mand line options. 

This chapter covers the Dialog Manager and the creation of di- 
alog boxes. Background information is provided initially, with de- 
scriptions of the different types of dialog boxes: 

• Modal dialog boxes 

• Modeless dialog boxes 

• Alerts 

This chapter also covers the items associated with dialog boxes and 
all their structures, options, and settings. This is followed by nu- 
merous programming examples and explanations. Unlike previous 
chapters, this chapter does not contain a complete programming 
example, though you can merge the About, dialog box example 
at the end of this chapter with the MODEL program introduced in 
Chapter 6. 



Chapter 11, which is about controls, adds a little more infor- 
mation to what's offered here. If you're interested in creating 
custom dialog boxes with your own controls, it's recom- 
mended that you read Chapter 10 first, then Chapter 11. 



Background Information 

Dialog boxes are controlled by the Dialog Manager. But actually, 
more than any other tool set, the Dialog Manager relies on a num- 
ber of other tool sets to help get the job done. For example, from 
the previous chapter, you might have read that the Window Man- 
ager contributes to the Dialog Manager by drawing the actual dia- 
log box. Also, the Control Manager (covered in the next chapter) 
helps out by drawing, manipulating, and regulating the controls in 

a dialog box. 

To use dialog boxes in your programs, you'll need to have 
started the following tool sets; 

• Tool Locator 

- Memory Manager 

• Miscellaneous tool set 

• QuickDraw II 

• Event Manager 



Dialog Boxes 

• Window Manager 

• Control Manager 

• LineEdit tool set 

(Also refer to the table of tool set dependencies in Chapter 4.) 

It may seem rather strange that the LineEdit tool set is re- 
quired to use a dialog box. In fact, you cannot display any text in a 
dialog box unless you've started the LineEdit tool set. The main 
reason LineEdit is needed is to manipulate text in a text input box 
(EditLine item). 

The text input box, as well as numerous other goodies you can 
put into a dialog box, are covered in Chapter 11, which deals with 
controls. 

The Dialog Manager is started by a call to the DialogStartUp 
function and shut down by a call to the DialogShutDown function. 
The Dialog Manager shares direct page space with the Control 
Manager, so there's no need to specify direct page space when 
starting this tool set. 

In machine language, the following code can be used to start 
the Dialog Manager (remember that the above-mentioned tool sets 
should also have been started): 



puBhword 
-Dialogs tar-tUp 



UserlD 



:push the program's User ID 
;.No errors possible 



. 



In C and Pascal: 
DialogStartUp(UB8rID); 

To avoid compile-time errors, C programmers should note that 
the <dialog.h> header file should be included at the top of your 
program along with the header files for all the other tool sets that 
are started up. 

To shut down the Dialog Manager, the following routines can 
be used. 

In machine language: 

—DialogShutDown 

In C: 
DlalogShutDownO; 

And in Pascal: 

DialogShutDown; 
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Once the Dialog Manager is started, your program can display 
dialog boxes. The dialog boxes can be defined in three ways, using 
three separate, yet similar, Toolbox calls. Once the dialog box is ac- 
tivated, there are special Dialog Manager calls that monitor the 
events in the dialog box. All these techniques, including examples 
of several dialog boxes, are described below. 

Types of Dialog Boxes 

As was mentioned earlier in this chapter, there are three types of 
dialog boxes: 

• Modal 

• Modeless 

• Alert 

Modal. A modal dialog box is the most common traditional 
type of dialog box. It's typically a rectangle filled with controls or a 
message. The dialog box is where a dialogue can take place be- 
tween the user and the program. A model dialog box allows the 
user to set or change an option or it can simply display information 
as in an About. . . or a Help dialog box. 

Modeless. The modeless dialog box is the least understood of 
the three. It's basically a window with dialog controls in it. Unlike 
the modal dialog box, which is always the foremost window, a 
modeless dialog box can be placed behind other windows, moved, 
zoomed, or manipulated like a regular window. Because of this ex- 
tra activity, the modeless dialog boxes are a little harder to pro- 
gram. Also, their use is vaguely defined, so you won't see them 
very often. 



Modal? Modeless? How can you remember which one does 
what? 

A good question. Think of a modal dialog as one that puts 
you in a mode where you're essentially forced to interact only 
with that dialog. A modeless dialog box is one without such 
restrictions: It's present on the DeskTop, but doesn't force you 
to interact with it. 
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Alert. The third type of dialog box, the alert, displays a warn- 
ing and, to varying degrees, a message. Alerts can have 
OK/Continue or Cancel/Stop buttons in them. The alert dialog 
boxes are actually specialized forms of modal dialog boxes. 

Refer to the Human Interface Guidelines Appendix for more 
information on the use of the dialog box as well as for design 
guidelines. 

Creative Overview 

Dialog boxes are easy to use. About the hardest thing they require 
is that you organize your thoughts about what to put into them. 
Utilizing a combination of tool set functions, the Dialog Manager 
simplifies the monitoring of dialog box events. Your program acts 
upon those events and performs whatever actions are necessary. 

Dialog boxes, like windows, require tables, locations, pointers, 
strings— a lot of information. In fact, positioning the controls is the 
only difficult thing about doing one. You'll spend more time mak- 
ing minor adjustments in the way things are displayed than you 
will placing them into the dialog box, or debugging logic. 

The steps to building a standard, modal dialog box are as 
follows: 

1 . Define the dialog box. 

2. Place items into the dialog box. 

3. Wait for a dialog event. 

4. Act on the event (repeat steps 3 and 4 as needed). 

5. Close the dialog box when you've finished. 

Steps 3 and 4 are repeated as various options in the dialog box 
are set. According to the Human Interface Guidelines, at least one 
button in the dialog should be responsible for closing the dialog 
box and making it go away, Typically, two buttons, OK and Can- 
cel, are used for this purpose. 

Actually, a dialog box could contain only a text message such 
as the famous saying, Please wait while I initialize. As soon as the 
program was ready, it could remove the dialog box and then 
proceed, 

In step 1, the dialog box is defined. It is placed on the screen 
as a special type of window, in front of all other windows on the 
screen. There are a number of calls to create the different types of 
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dialog boxes. In fact, there are three separate Toolbox calls used to 
create a standard modal dialog box (each is covered later in this 
chapter). 

After the dialog box is created (by whichever method), the Di- 
alog Manager returns a pointer used to further reference the dialog 
box, just as the Window Manager returns a pointer to a window. 
The pointer returned by the Dialog Manager is used to place items 
into that particular dialog box, as well as to remove the dialog box 
once you've finished with it. 

Step 2 is where items are placed into the dialog box. Each item 
has a position relative to the top left corner of the dialog box (local 
coordinates), an item description, and a type. The individual 
characteristics of the items, or controls, placed into a dialog box are 
covered in the next section. 

Steps 3 and 4 are where all the activity takes place. The Dialog 
Manager has special functions that monitor dialog box activity. 
These functions take advantage of the TaskMaster and Event Man- 
ager to make tracking the events in a dialog box quite simple. 
When a user selects a particular control, your program can deter- 
mine which control was selected and take appropriate action. 

Once the user has finished with the dialog box (OK or Cancel 
has been clicked), the dialog box is closed, just like a window. The 
dialog box can be called up again a number of times by simply re- 
peating these steps. See below for individual examples of how 
these steps are implemented. 

Modal dialog boxes will, without exception, follow the above 
five steps. Alert boxes are special exceptions. With alerts, the first 
three steps are combined (most of the work is done internally, by 
the Toolbox). Alerts are used only to get an immediate yes/no re- 
sponse from a user. Therefore no additional action is taken upon 
them. They are first displayed; then they get the input and are fi- 
nally removed so that your program can continue with the action 
or stop what it's doing. (See the section on alerts below for more 
information.) 

Modeless dialog boxes are handled in a completely different 
manner. A modeless dialog box is displayed; however, unlike 
modal dialog boxes and alerts, it need not be acted upon right 
away. The user can move it behind other windows on the DeskTop, 
or ignore it completely and go off to do something else. Because of 
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this, modeless dialog boxes have a special way of handling their 
events. (Refer to the section on modeless dialog boxes below for 
additional information.) 

Dialog Box Controls 

The things placed into a dialog box are called controls. Buttons are 
a common type of control, as are radio buttons, check boxes, text 
input boxes (EditLines), pictures, icons, and even blocks of text. 

Every control placed into a dialog box has a special ID number 
associated with it. It's this value that is monitored by the Dialog 
Manager's special event-handling routines (step 3 from the previ- 
ous section). When the user clicks on that control, the ID number is 
returned for your program to examine. Simple. 

Besides assigning an ID number, you also need to define what 
type of item is placed into your dialog box, where it is placed, 
whether it's visible, invisible, disabled, and so forth. In all, you 
need to tell the Dialog Manager seven things in order to place a 
control into a dialog box (see Table 10-1). 

rameters for Placing Controls in Dialog Boxes 

Meaning 

The control's special ID number 

The control's position inside the dialog 

The type of control; button, text, icon, and so on 

A pointer to special information about the control 

The initial value of a control 

Visible/invisible flag, as well as other information 

A table defining the dialog's color 

These items are placed into the dialog box either individ- 
ually — by using the NewDItem Toolbox call — or all at once — by 
using a template of information, or record, and using the 
GetNewDItem or GetNewModalDialog calls. 

Individually, each item is described as follows. 

ItemID. The ItemID is a value assigned to each control in your 
dialog box. It can be any value in the range $0001-$FFFF. (An Item 
ID of is possible, but not recommended, because of potential con 
flicts with certain Toolbox calls.) 

An ItemID of 1 is reserved for use by the dialog's default but- 
ton. Pressing the Return key is considered the same as clicking on 
the item with an ItemID of 1. Typically, the OK button is given an 



Table 10-1 


Seven Pa 


Name 


Value 


ItemID 


Word 


ItemRect 
ItemType 
JtemDescr 
Item Value 


Rectangle 

Word 
Long 

Word 


ItemFlag 
hemColor 


Word 
Pointer 
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ID of 1, Also, if a button has an ID of 1, that button has a double 
outline. 

An ItemlD of 2 is reserved for the dialog's Cancel button. 
Pressing the Escape key is the same as selecting the item in a dia- 
log box with an ID of 2. 

Feel free to give the items in your dialog box any number 
other than 1 and 2 (and 0). A good technique is to give each dialog 
box an ID in the MSB of the ItemlD, then number the controls se- 
quentially starting with 0. 

For example, assume your dialog box is given the arbitrary 
value $0055. Then assign each control in the dialog box (except the 
OK and Cancel buttons) with IDs of $5500 plus the sequential 
value of the specific button. Refer to the programming samples be- 
low for examples. 



The default button, ItemlD $0001, is a good thing to have in 
any dialog box, especially when you're first writing routines 
and experimenting. Because pressing the Return key is the 
same as clicking the default button, if you ever make a terrible 
formatting mistake (like creating a tall, skinny dialog box with 
no visible text or controls), you can still press Return to avoid 
having to reset your computer to start over. This might not ex- 
actly be the intent of the default button, but by trial and error, 
most programmers discover this technique. The authors have 
become very adept at this. 



ItemRect. The ItemRect defines the control's position relative 
to the upper left corner of the dialog box (which is local coordinate 
0,0). The ItemRect is defined as four words setting the upper left 
corner and lower right corner of the control's location as follows: 

• Upper Left Y value (MinY) 

• Upper Left X value (MinX) 

• Lower Right Y value (MaxY) 

• Lower Right X value (MaxX) 

Any text in your dialog box must fit inside the given rectangle. 
If you make that rectangle too small, not all the text will be visible. 
And if you make the rectangle too large, the text might overlay 
other controls in the dialog box. 
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With some controls, such as buttons, you need only define the 
upper left coordinate, using a value of for the lower right coordi- 
nate. The lower right values are calculated based on the size of the 
text inside the control. (This calculation is performed automatically 
by the Control Manager.) For example, 

dc 12 , 70,130.0.0' 

is all right to define the location of a button. The MaxY and MaxX 
values are set according to the text in the button. 



In machine language and C, the values of a rectangle are 
given in MinY, MinX, MaxY, MaxX order. But in TML Pascal, 
coordinates use the MinX, MinY, MaxX, MaxY order. Keep this 
in mind when converting programs between these languages. 



ItemType. The ItemType parameter describes the type of con- 
trol. ItemTypes in the following table are listed next to the items 
they define. 

Table 10-2. ItemTypes and the Control They Describe 



ItemType 


Description 


Name 


Definition 


$000A 


Button 


Buttonltem 


Activator 


$000B 


Check box 


Checkltem 


Switch 


$000C 


Radio button 


Radioltem 


Switch 


$000 D 


Scroll bar 


ScroIlBarUem 


Special dialog control 


$000E 


User control 


UserCtlltem 


User-defined 


$000F 


Text 


StatText 


Characters (up to 255) 


$0010 


Text (longstat) 


LongStatText 


Characters (up to 32,767) 


$0011 


EditLine 


EditLine 


Input box 


$0012 


Icon 


Iconltem 


Graphic image 


$0013 


Picture 


Picltem 


Graphic image 


$0014 


User item 


Userltem 


User-defined 


$0015 


User control 2 


UserCtlItem2 


User-defined 



Currently, only the above ItemTypes are defined. So, for ex- 
ample, to define a check box in your dialog, you'd specify an item 
type of S000B (as well as providing the other information indicated 
in this section). 

To disable any item in the dialog box (so that clicking the 
mouse on that item will not generate a dialog event), logically OR 
the ItemType with $8000 (which is the same as adding $8000 to 
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the item value). For example, most text items in a dialog box are 
disabled, meaning that clicking on them doesn't do anything. To 
define a disabled text item, the following ItemType can be used: 

do i2■$800? , 

This might also be expressed using equates in machine lan- 
guage (see the examples below), as in 

do tS'ltenmisable + StatTaxt' 

where ItemDisable equals $8000 and StatText equals $O00F. 
In C, the expression 

(ItemDisable I BtatTsxt) 

is equivalent to adding these two items, though more logical. 

ItemDescr. The ItemDescr is a long word, either a pointer or a 
handle, depending on the ItemType (see Table 10-3). 

Table 10-3. ItemType Determines What Is Pointed to by ItemDescr 

ItemType ItemDescr 

Picture Picture's handle 

Button Pointer to a string to be placed inside the button 

Check box Pointer to the check box's title string 

Radio button Pointer to the radio button's title string 

Scroll bar Pointer to an action procedure controlling a scroll bar 

User control Pointer to the control's action procedure 

Text Pointer to the text string 

Text (longstat) Pointer to the beginning of the block of text 

EditLine Pointer to a text string or buffer 

Icon Icon's handle 

User item Pointer to a definition procedure 

User control 2 Pointer to a parameter block 

All string pointers above indicate the memory location of a 
Pascal-type string. 

ItemValue. The ItemValue of a control contains the control's 
initial value, or in most cases (see Table 10-4). 



196 



■ Dialog Boxes 

Table 10-4. Values Contained in ItemValue 

ItemType ItemValue 

Picture Pointer to the picture's image 

Button Initial value of the control 

Check box $0001 to check the box, $0000 for unchecked 

Radio button $0001 to fill the button, $0000 to leave it empty 

Scroll bar Value passed to the scroll bar's definition procedure 

Text Not important 

Text (longstat) Number of characters in the text block (up to 32,767) 

EditLine Maximum number of characters to be entered (up to 255) 

Icon Not important 

User item Initial value of the control 

User control 2 Initial value of the control 

The value can be examined or changed using the Dialog Man- 
ager Toolbox calls GetDltemValue and SetDltemValue. For ex- 
ample, suppose a radio button is to be activated based upon some 
change in the program. The following routines wilt change the 
ItemValue of the radio button. 

In machine language: 



EoartHS 



anop 

pha 

puflhlong 

pushword 

—GetDltemValue 

pi* 
bne 

pushword 



Go_0n 



pushword 

—SetDltemValue 

anop 



DtalogPtr 

'RButtonl 



(3o_0:n 

$0001 

DlalogPtr 
►RButtonl 



;push one word result space 
;tbe pointer to the dialog box 
;tne ItemtD or the radio button 
;return Its value 

■.test the Item's current value 
;lf If e already 1, don't change It 

;the new value for the Item (l = on) 



:set the new value 



Note: GetDltemValue and SetDltemValue return an error 
($150C) if the ItemID specified does not exist or does not belong to 
the specified dialog box. 

InC: 

If (IGetDItemValueCDlalogPtr, RButtonl)) 
SetDItemValue(l. DlalogPtr-. RButtonl); 
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in Pascal: 



IF GetDItemValue(DlalogPtr. RButtonl) = THEN 
SetDItemValue(l. DlalogPtr, EButtonl); 

Note: Clicking on a radio button or check box does not auto- 
matically activate it. Your program must do that. 

The value of the radio button can also be set when the dialog 
box is initially created. However, the above routines are preferred if 
the state of the radio button changes. See the COLOR example be- 
low. Also, be careful not to confuse changing the Item Value with 
making it invisible or disabling it. 

ItemFLag, The IternFlag is used mainly by the Control Man- 
ager to control certain aspects of some controls— for example, the 
outline of a button or the orientation of a scroll bar. Refer to Chap- 
ter 1 1 for information on the IternFlag. For now, setting IternFlag to 
in your routines is acceptable. 

ItemColor. ItemCoIor is a long word that points to a color ta- 
ble. The color table is used by the Control Manager to change the 
colors of the item. Normally, this item is set to a long word of 
and the standard colors are used. Refer to Chapter 11, which deals 
with controls, for a description of the color table and an example of 
changing an item's color. 

A Dialog Box 

There are three "official" methods for placing a modal dialog box 
on the screen. The first one is the most complex. It pushes all infor- 
mation about the dialog box on the stack, then calls the Dialog 
Manager a number of times (once to create the dialog, then one 
time for each item in the dialog) until everything's finished. 

The other two methods use templates of information. These 
templates merely contain all the data that is pushed to the stack in 
the first method. However, with templates, only a pointer to a tem- 
plate, or simply to one master template, is pushed to the stack. The 
Dialog Manager does the rest. 

The complex method of creating a dialog is covered in this sec- 
tion, along with important background information. The methods 
using the templates appear in the following two sections. 
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To create a dialog box, you must tell the Dialog Manager the 
following three things: 

• The location and size of the dialog box 

• Whether the dialog box is visible or not 

• A long word value, DRefCon 

The DRefCon is a value your program can define for its own 
use. As with the wRefCon value used by the Window Manager to 
define a window (see Chapter 9), this value is typically set to 0, but 
it can be set to any value you'd like. 

From the Dialog Manager your program will receive a long- 
word pointer to the dialog's port, or a long word of if there was 
an error. This value should be saved for all further references to 
your dialog box. 

Once the dialog is established, you can start placing controls 
into it. As with creating a dialog box, the controls can be created by 
pushing their values on the stack and calling a Dialog Manager 
routine to install them one at a time, or you can use templates to 
install them all at once. 

Simply creating and placing the dialog items does not make 
them appear in the dialog box. They all suddenly appear the first 
time you make a call to the ModalDialog function — which is a 
good thing, because that's what your program will use to handle 
dialog events. 

When the desired controls have been placed into the dialog 
box, the ModalDialog function handles dialog events, just as the 
Event Manager or TaskMaster handles desktop events. Modal - 
Dialog also initially places all the items into the dialog box. (The 
items are not visible until ModalDialog is called.) 

The ModalDialog function is used only for modal dialog boxes. 
Modeless dialog boxes and alerts use their own methods for trap- 
ping dialog box events. These techniques are discussed in a later 
section. 

ModalDialog waits for the user to click the mouse on a control. 
When this happens, the ItemID of the control is returned by the 
ModalDialog function, even for EditLine items. Your program can 
then take whatever action is necessary. 

Once the function of the dialog box is served, close it, remov- 
ing it from the screen, with the CloseDialog function. 
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It's important to include some way to close a dialog box. In 
other words, build in an option for the user to tell the dialog box to 
go away. It's embarrassing when professional programmers and gu- 
rus create magnificent dialog boxes and then realize they have no 
way of escaping from them. 

Important Pascal Note 

At the time of this writing some important TML Pascal data types 
for the Dialog Manager had not been finalized. So, for your pro- 
gramming pleasure, a set of records and data types are listed next. 
These are all related to working with dialog boxes and alert boxes 
in Pascal, and they are used throughout the examples in the rest of 
this book, You can incorporate this information into your programs 
as needed. 

Note that the remainder of this book refers to these types as if 
they were automatically built into a TML Pascal unit symbol file. 
The definitions of these types won't be shown again. 

1 TML Pascal Dialog and Alert Type DsnnltlonB } 
CONST atltemLlBtLength - 4; 

dUtemLlstLength — 8; 

ItemTempPtr = "ItemTemplate; 

ItemTemplate = PACKED RECORD 



TYPE 



ItemlD: 

ItemRect: 

ItemType: 

ItemDescr: 

itemVahie: 

ItemFlag: 

ItemColor: 



Integer; 

Rect; 

Integer; 

Ptr; 

Integer; 

Integer: 

Ptr; 



END; 



DlalogTemplate = RECORD 

dtBoundsRsct: Rect; 

dtVlslble: Boolean: 

dtRefCon: Longlnt; 

dtltemlilflt: ARRAY [O.dtlteniLlstLeiigth] OF ItemTempPtr; 
END; 

Alert-TempPtr = "ALertTempIate; 
AlertTemplate = RECORD 

atBoundsRect: Rect; 

atAlertID: Integer; 

atStagel; SignedByte; 
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atStage3 
atStage4 



SignedByte 



SignedByte: 



atltemLlfit: ARRAY [0..atItemLlstLengtfa] OF ItemTempPtr; 



k?;;j, 



Check your version of TML Pascal to see whether these types 
(or similar types) are defined. If they are, the names might be dif- 
ferent. (The authors did their best to choose record and field names 
that seemed the most logical, but they're not clairvoyant.) 

Doing a Dialog, the Long Way 

The first Toolbox function used to create a dialog box is 
NewModalDialog. It receives its information on the stack rather 
than using a template. The following routines can be used to create 
a modal dialog box using the NewModalDialog function. 
In machine language: 

LadyDl 



pha 




;long word result apaoe 


pha 






puBblong 


'DlalogRect 


;rectangle pointer 


pushword 


TRUE 


;make dialog visible (TRUE 



pea $0000 

pea $0000 

—NewModalDialog 

Jsr ErrChk 

pulllong DlalogPtr 
rts 



;DRefCon - any value 

:make the call 
;checls for errors 



;the dialog pointer 
L2'40,30.100,2SQ' ;lte position and size (320 mode) 



DlalogRect do 

InC: 

Root DlalogRect = { 40, 30, 100. 290 }; 

LadyDiO 

< 

DlalogPtr = NewModalDlalog(&DlaIogRect, TRUE, NULL); 



In Pascal: 

PROCEDURE LadyDl; 
VAR DlalogRect : Rect: 
BEGIN 

SetRect(DtalogRect, 30. 40. 290, 100); 

DlalogPtr := NewModalDlalog(DlalogReot, TRUE. Longlnt(nll)); 
END; 
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DHeight 


equ 


DWldtb 


squ 


DlalogReot 


dc 




dc 




dc 




dc 
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The size and position of the dialog box are specified by the 
rectangle passed to the NewModalDialog function. According to 
the Human Interface Guidelines, dialog boxes should be a little 
higher than screen center and centered left to right. The following 
machine language equations can be used to center a dialog box. 
The DHeight and DWidth parameters represent the dialog box's 
height (Y pixels) and width (X pixels), respectively. 

?? ;Your dialog's height goee hare 

?? ;Youp dialog's width goes here 

tatiso-DHeightj/a* 

12'(190-DHelght)/2 + DHeljhV 
12'(&40-DWldth)/2 + DWldUY 

For a dialog box in the 320 screen mode, change the number 
640 above to 320. The value 190 is used for the maximum number 
of Y pixels to place the dialog box a little above center screen. (It 
looks awkward when a value of 200 is used.) 

This technique can be used in your programs as needed, either 
as a pointer or as part of a dialog's template {see below). Remem- 
ber to replace the DHeight and DWidth values in the template with 
the equates (or values) representing the size of your particular dia- 
log box. 

Items placed inside the dialog box are given in local coordi- 
nates relative to the upper left corner of the dialog (position 0,0). 
This allows you to move or resize the dialog box without affecting 
the internal location of the items. 

Items inside a dialog box are placed there by a call to the Dia- 
log Manager's NewDItem function. NewDItem requires the infor- 
mation listed in Table 10-5 for the item you're placing into the 
dialog. 

Information Required by NewDItem 

Description 

A pointer to the dialog box 

The control's ID number 

A pointer to the control's position 

The type of control 

A pointer to special information about the control 

The control's initial value 

Miscellaneous information about the control 

A pointer to the control's color table 
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Table 10-5. 


Inform 


Parameter 


Size 


DialogPtr 

ItemFD 


Long 
Word 


UemRect 
ItemType 
ItemDestr 
I tern Value 


Long 
Word 
Long 
Word 


Item Flag 
HemColor 


Word 
Long 



Dialog Boxes 

In the following programming examples, the first control de- 
fined is the OK button; the second control, a block of text. 
In machine language: 



Buttonltem 


equ 


I0OOA 




Textrtem 


equ 


tOOOF 




ItamDIeable 


SQU 


16000 




TrlokD! 


push long 


DialogPtr 


dialog in which to place this control 




push word 


10001 


the ItemID, 1 = default button 




pushlong 


'ButtonRect 


rectangle pointer for the button 




pushword 


Butwnltem 


this Item is a button, type tOOOA 




push long 


'ButtcnTsxt 


text inside button 




puBhword 


to 


Initial value (not Important) 




pushword 


•0 


HemPlag, zero for default 




pushlong 


10 


color table, zero for default 




_NeirDItem 




make the call 




Jer 


ErrCh.lt 


check for errors 




pushlong 


DialogPtr 


second Item: text block 




pushword 


$1234 


ItemID, can be anything 




pushlong 


•TextRect 






pushword 


Textltem •) ItemDlaable 






pushlong 


* re it Text 






pushword 


to 






pushword 


10 






pushloag 


to 






—NewDItem 








Jmp 


ErrChk 




ButtonReot 


dc 


IZ'aB.lBO.O.O' 


Ite position In the dialog (relative) 
ButtonText 


sir 


•OK' 


ibuttons text 




TextRect 


dc 


12'1Q,60.3Q.24Q' 




TextText 


str 


'Press the OK button' 





InC: 

Rect ButtonReot = { 35. 150. 0, }; 
Reel TextReot = { 10. 80, 30, 240 }: 

TrlokDlf. ) 

{ 

NewDItem(DlalogPtr. 1. feButtonRect, buttonltem, 

"\pOK", 0, 0, NULL); 
ErrChkO; 
NewDItemCDlalogPtr. 0x1234. fcTextRact, textltem + ltemDlsable, 

" \pPreas the OK button", 0, 0, NULL); 
ErrChk{ ); 



. 
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In Pascal: 

PROCEDURE TrlokDt; 
VAR ButtonHect : Reel; 

TextRact : Rect; 

ButtonText : String; 

TextText : String; 
BEGIN 

ButtonText : = 'OK'; 

TextText ; = 'Press the OK button'; 

Set.Rect(ButtonRact, 150. 35. 0, 0); 

SetRaetfTextFect, 60, 10, 240,. 30); 

N8wDItem(Dlal«jgPtr, 1, ButtonRect. Buttonltem, 

^ButtonText, 0. 0, nil); 

ErrChk; 

N8wDItem(DlalogPtr, *1234. TextRact. StatTextltem + ItemDlsable, 

^TextText, 0. 0, nil); 
ErrChk; 
END: 

Once all the controls have been placed in the dialog box, the 
ModatDialog function is called to monitor dialog events. ModalDialog 
returns the ItemID of the control selected with the mouse, The fol- 
lowing routines incorporate the previous two examples to monitor 
the pressing of the OK button. When OK is pressed, the dialog box 
is closed via the CloseDialog function. 
In machine language: 



Walt pha 

pushlong 
_ModalD)alog 


DlalogPtr 


one word result space 
this dialog 
make tbe call 


put 

emp 
bne 


'41 

Walt 


gat results, toe ItemID 
was It OK? 

keep waiting If not OK 


pushlong 
_ClQsaDialog 


DlalogPtr 


close this dialog 
do It 


In C: 






while (ModalDlalog(DlalogPtr) 1- 1); 
ClOBaDlalog(DlalogPtr); 





In Pascal: 

REPEAT UNTIL (ModalDlalog(DlalogPtr) = 1); 
CloBeDlalog(DlalogPtr); 
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Once the dialog is closed, the Event Manager/TaskMaster con- 
tinues monitoring your DeskTop events. The dialog can again be 
opened to obtain input, adjust settings, or communicate a message, 
simply by repeating the above steps. 

Making It Easier 

The only thing wrong with the routines in the previous section is 
that they involve a lot of typing (especially in machine language). 
When you replace the information pushed to the stack with tem- 
plates of information, the actual code used to create the dialog box 
becomes easier to read. Also, updating the dialog box is easier be- 
cause you're changing data templates rather than changing actual 
program code. 

To add a control to a dialog box using templates, the 
GetNewDltem function is used. GetNewDItem does the same thing 
as NewDItem, except the information is in a template, and a long 
pointer to that template is passed to the Toolbox. Refer to Table 
10-6 for details about the structure of the template. 

Table 10-6. Structure of GetNewDItem Template 



Offset 


Size 


Parameter 


+ $00 


Word 


ItemID 


+ $02 


Four words (rectangle) 


ItemRect 


+ S0A 


Word 


Item Type 


+ $0C 


Long word (pointer) 


ItemDescr 


+ $10 


Word 


Item Value 


+ $12 


Word 


ItemFJag 


+$14 


Long word (pointer) 


I tern Col or 



The following routines are similar to those found in the previ- 
ous section. They define the same two controls — a button and a 
block of text — using the GetNewDItem function. 

In machine language: 



Button Itam 


aqu 


4000A 




Taxtltem 


equ 


4000F 




ItemDlaable 


aqu 


18000 




Putl terns 


anop 








puBhlong 


DlalogPtr 


.dialog In which to 
:placa this control 




pushlong 


*ButtonRec 


:the button's template 




.GetNewDItem 








Jsr 


BrrChk 


;test for errors 
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pu&blong 




DlalogPtr 


.dialog in which to 
;place this control 


ButtonRec 


pushlong 

_GatNewDItem 

Jmp 

anop 

dc 

dc 

do 

dc 

dc 


•TextRec 
ErrChk 

WV 

12-35,150.0.0' 
12'ButtonItem' 
14 'ButtonText' 
12'0' 


;the text's template 

;the button's template 

.ItemlD, 1 

■.rectangle for the button 

:ttemType 

.pointer to button's text 

•.initial value (not 




dc 




12'0' 


important) 
;ltemPLag. zero for 




dc 




140' 


;default 

;color table, default 


ButtonText 

TsitReo 


str 

anop 

do 

dc 

dc 

dc 

dc 

dc 

dc 




'OK' 

12'U234' 

12'10.6Q.30,240' 

12'TextItem+ ItsmDlsable 

14'TextTexf 

WO' 

LS'O' 

14'0" 


:button'e text 

;the text's template 


TextText 


tr 'Press the OK button' 




In C: 










ItamTampl&ta ButWnRoo - [ 
1, 

36, 160. 0. 0. 
bullonlWm. 
"\pOK". 
0, 
0. 
NULL 


r 

r 
r 
r 

/' 

■■ 
i 


llauID - 1 7 

rectangle to Ui» button 7 

IWmTyjM 7 

button '• text 7 

ItamViUM 7 

ltamFlag 7 

color iabl«. 4»l«uit 7 




[WmTsmpliie TeitRM = 1 
0«12S«. 

10, BO. 30, MO, 
tail! torn + ItamDlteble 









Dialog Boxes 



" v pPnti the OK button". 

0, 
0, 

irau 



Putltama( ) 
I 



GeUI«wDIt*m(DlalogPtr, *ButlonRec): 
GeUtawDItempialogPtr. *TeriR«o); 



RrrChk( J; 
BrrChk( ); 
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In Pascal: 






PROCEDURE PulIUmt; 






VAR ButtMiBw . 


ItemT»nip!ata. 




TsztRec 


ItemTamplaw. 




TaxtTsW : 


String. 




BwuonTwrt ' 


String. 




mm 






TKtTut 




= 'Ptbsb ttifl OK button'; 


BuUoaTeit 




- -OK'; 


WITH ButWnRM DO B8GIN 




IttmID 




- i; 


SelRaot (ItomBsct 


180, 38. 0. 0); 




ItamTypa 




— Buttonltam. 


IttaDwor 




= ffButlonTBiv 


1 lam Value 




- 0; 


Itemflag 




- 0: 


iwmcolor 




- nil; 


END; 






WITH TsttRso DO BEG1K 






lia ml D 




- IJ234. 


SstRecKIUmRoct. 


SO. 10. 210. 30); 




ItenType 




- IwaiDlsalj]«+Sl»tT*rtitem; 


IWmDBSop 




» rMlText; 


ItemVslus 




C; 


mana 




- 0; 


lUnCoIor 




= nil; 


nc 






&BUiewDIlem(D)«lQ«Pti\ 


ButtonB«C), BrrCtik; 




GttN»wDIttni(D!alo«Ptr. lertRso). BrrCnt 





END, 

The other routines from the previous section, NewModal- 
Dialog and ModalDialog (for dialog box event trapping), would still 
be used as written. The GetNewDItem only aids in the creation of 
controls. 

Do you get the feeling that perhaps you should have started to 
read this chapter from the end and then worked backwards? 
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The final step to creating a dialog box easier is just to use one 
big template for everything— that is, for the dialog box as well as 
all the controls in the dialog box. This way, creating a dialog box 
with all its goodies is done with just one Dialog Manager Toolbox 
call; GetNewModalDialog. 



GetNewModalDialog would seem to be the longest-named 
Toolbox function. Well, it is. At 17 letters, it ties with 
FF §6URa.D8Re'§talU§ Ind TLT§«M0Unt\felum6: GetNew- 
ModalDialog works internally by calling NewModalDialog and 
then GetNewDltem for each item in the template. 



The template used by GetNewModalDialog contains the infor- 
mation listed in Table 10-7. (Note how it also incorporates the tem- 
plates used by GetNewDltem.) 

Table 10-7. Information Required by GetNewModalDialog Template 
Offset Size Parameter Description 

Four words (rectangle) BoundsRect 

Word 

Long 



+ $00 
+ $08 
+ $0A 
+ $0E 
+ $12 



vord 

Long word (pointer) 
Long word (pointer) 



dtVisible 

dtRefCon 

HemPtr 

ItemPtr 



+ $?? Long word 



Terminator 



Size/location of dialog box 
Visible/invisible flag 
Whatever you want 
First item's template 
Second item's template 
(and so on) 
Zero, end of template 



The dialog box's template contains all the information passed 
to the NewModalDialog function, as well as pointers to the control 

Item S templates used by Ihe GclNc>vDItom function Thp la«t item 

in the dialog box's template is a long word of to indicate the end 
of the template. This way, your dialog box can have a multitude of 
items (though that's not recommended). See the COLOR example 
below for a really huge template example. 

Incorporating all the information from the previous two sec- 
tions, the following examples create the dialog box and place all 
those items into the dialog box. Use the ButtonRec and TextRec 
data from the examples in the previous section to complete the ex- 
amples below. 
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In machine language: 



PutI terns 



anop 

pha 

pha 

push long 

-GetNewModalDialog 

JSP 



DialogRec 



rts 

anop 

do 
do 
do 
do 
do 
do 



InC: 

DtalogTemplate DlalogReo = { 



'DlalogReo 



ErrCnk 
DlalogPtr 



12'40.30.100,S 
12 "TRUE" 
14'0' 

K'ButtonR&c" 
14- TextRec' 



:long word result epaoe 

dialog's template 
;do it alll 
icheok for errors 

;the dialog pointer 

;dlalog"s template 
;dialog"B rectangle 
;vistble flag 
;DRsfCon - any value 
;flrst control's template 
isecond control's template 
;null terminator 



40, 30, 100, 290, 

THUS. 

NULL, 

ftButtonRec, 

tTextRec. 



NULL 



/• dialog's rectangle */ 

/' visible flag ■/ 

/• dtRefCon 7 

/• first control's template •/ 

/' second control's template •/ 

- - --' - ■•—»■—•» i 

/' null terminator •/ 



Putlteine( ) 

: 

DlalogPtr = GetNewModalDlalog(&DlalogRec); 
} 

In Pascal: 

PROCEDURE 

Putltems; 

VAR DialogRec : DlalogTemplato; 

BEGIN 

WITH DialogRec DO BEGIN 

SetRectCdtBoundsRect. 30, 40. 290, 100): 
divisible :- TRUE; 

dtRefCon := Longlnt(nll); 

dtItemLlst[0] ;= ^ButtonRec: 
dtItemLlst(l] := ^TextRec; 
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dtItemLlBt[2] 



:= nil: 



END; 
DlalogPtr 



: = GetNewModalDlatog(«rDlalogFlec); 



END; 

Following the above routines, your program should monitor 
the dialog events with the ModalDialog function and, when fin- 
ished, close the dialog box with the CloseDialog function. Unfortu- 
nately, there are no simple shortcuts for those two calls. (After all, 
they really are simple themselves.) 

The list of ItemTemplate pointers in C is actually an array 
which has eight elements allocated. If your program has a dialog 
box that contains more than eight items, you'll have to increase the 
size of that array to handle more elements. This is done by defin- 
ing a constant dtltemListLength. It should be placed before the in- 
clude <dialog.h> directive at the top of your program— for example: 

'define dtltemListLength 14 /■ define a larger Item array '/ 

•include <diatog.h> 
Pascal programmers need only change the dtltemListLength 
constant in the CONST section of their programs. 

Alert Boxes 

An alert box is a special type of dialog box. It's used to display a 
message and usually offers two buttons: 

• One to go on (OK) 

• One to stop whatever action is taking place (Cancel) 

Events in alerts are handled by the function that creates the alert. 
Only one event can be acted upon and then the alert box disappears. 

There are four functions to create an alert, each a warning of 
increasing intensity: 

• Alert 

• Note alert 

• Caution alert 

• Stop alert 

The note, caution, and stop alerts all have graphic icons associ- 
ated with them, as seen in Figure 10-1, The basic alert has no 
graphic. You can define your own icon as the graphic, or just let it 
go as a text-only alert. 
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Figure 10-1. Three Alert Boxes 



lins is a note alert. 



A 


This is u caution alert. 


J 


U Cancel J) [ OK 







o 


This is a stop alert. 




f 1 ..l.i i-l j [IK 


J 







The functions to bring up the above alerts are as follows: 

Dialog Manager Function Type of Alert 

Alert Empty alert box (no icon) 

NoteAlert Man and cartoon balloon icon 

CautionAlert Exclamation point icon 

StopAiert Stop sign icon 

These functions are a combination of GetNewModalDialog and 
ModalDialog. One call to an alert function places all the controls in 
the specified dialog box (all using one template, as with GetNew- 
ModalDialog). Then, ModalDialog is called to monitor the events in 
the alert box. Control doesn't return from the Toolbox until an item 
(I tern Hit) is chosen. 

The only variance among the routines is in the icon drawn (or 
not drawn) in the upper left comer of the alert box. After an event, 
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the alert function closes the alert dialog box and returns with the 
ItemID of the item selected. So, there's really nothing to be done 
with an alert other than display a message and get a quick response, 

Because of the click-and-vanish aspect of alert boxes, they 
typically only contain text and an OK or Cancel button (or some- 
thing similar). If you're planning on an alert with more buttons, 
switches, or controls, you should create a modal dialog box instead. 

All the above functions use the following parameters to define 
an alert: 

Parameter Size Description 

AlertTemplatePtr Long word Pointer to a template 
FilterProcPtr Long word Pointer to a filter procedure 

The FilterProcPtr points to a user-defined routine to test the 
events detected by ModalDialog (all dialog events). This way, you 
can write your own filtering routines, either augmenting or replac- 
ing the standard routines used by the Toolbox. Usually, a long 
word of is specified to use the default routines. 

The template pointed to by AlertTemplatePtr contains the 
information listed in Table 10-8. 

Table 10-8, Information Required by AlertTemplatePtr Template 

Offset 

+ $00 



Size 

Four words (rectangle) 
+ $08 Word 
+$0A Byte 
+$0B Byte 
+$0C Byte 
+$0D Byte 

+ $0E Long word (pointer) 
+ $12 Long word (pointer) 

+ $?? Long word 



Parameter 

BoundsRect 
Alert ID 
Stage 1 
St age 2 
Stage3 
Stage4 
ItemPtr 
ItemPtr 

Terminator 



Description 

Size/location of alert 

Alert's ID number 

Alert stage (see below) 

Alert stage 

Alert stage 

Alert stage 

First item's template 

Second item's template 

(and so on) 

Zero, end of template 



The AlertID is simply a unique number identifying the alert 
box. Its value can be anything. 

The alert stages are used to monitor subsequent selection of 
the same alert box. An alert box is supposed to appear to warn the 
user of some pending catastrophe. Obviously, the more the alert 
box tends to pop up in a program, the more careless (or inattentive) 
the user is. So the differing alert stages can be used to progres- 
sively increase the warnings offered by the alert. 
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Table 10-9, Bit Values for Alert Stages 



Bit 


Meaning 






1 
2 


Number of beeps 
Number of beeps 

Not used 




3 


Not used 




4 


Not used 




5 


Not used 




6 


Sets default button 




7 


If set, alert is drawn; 


if 0, alert is not drawn 



As indicated in Table 10-9 and in Table 10-10, bits and 1 de- 
termine the number of beeps made by the alert. The beep sounds 
before the alert is drawn on the desktop. 

Table 10-10. Beeps Emitted as a Result of Bits Set in Alert Stages 

Bit 

1 o Beeps 

None 

1 One 

1 Two 

1 1 Three 

Bit 6 sets the default button in the dialog. If bit 6 is 0, the de- 
fault button is ItemID $0001; if bit 6 is 1, the default button is 
ItemID $0002. (Remember, the default button is selected either 
with the mouse or by pressing the Return key.) 

Bit 7 determines whether the alert is to be drawn or not. 

By subtly changing each subsequent alert stage, you can offer 
an increasingly severe warning each time the same alert appears. 
Or, you can opt to keep the same alert stage throughout the ap- 
pearance of your alert dialog. Incidentally, after alert stage 3, alert 
stage 4 will repeat for each succeeding appearance of the alert. 

The following demonstrates four alert stages, each offering a 
more severe warning than the last: 

dc trior ;stage one 

do 1TI8I' ;stage two 

do 11**82' :stage three 

dc U'*C3' ;staga four 

The first stage simply beeps the speaker once — the alert is not 
drawn, The second stage beeps the speaker once and the alert is 
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drawn. In the third stage, the speaker beeps twice before the alert 
is drawn. In the fourth and all following stages, the speaker beeps 
three times, the alert is drawn, and the default button is switched. 
This way, a user who is accustomed to seeing the alert and press- 
ing Return will not automatically continue to select the same op- 
tion. (He or she will have been foiled— or shocked back into 
reality, which is the purpose of the alert.) 



A lot of research and study has gone into the way people re- 
spond to computers. It seems that no matter how you warn 
users, no matter how many safeguards and warnings you dis- 
play, if they are set on doing something, they'll do it, even if 
that something could lead to catastrophic results. 

Ab an example, it's easy lo make on error using the com- 
mand to reformat a disk on an IBM computer. The only warn- 
ing offered is a simple yes/no prompt. As the accidental 
formatting of disks increased, the makers of IBM's DOS kept 
adding safeguards to prevent users from accidentally format- 
ting disks. This still didn't work. 

An alert box, on the other hand, has many tricks to con- 
tinually warn users of what they're about to do. The best is in 
bit number 6 of the alert stage. This bit switches the default 
button of an alert. So, if a user is accustomed to seeing the 



.j.... n.4 U . 



suiuc alcii pop up una uic imiuiui .^-.^w..-,. . 

you can circumvent that process by switching the way the 

alert responds to the Return keypress. 



As with the GetNewModalDialog function, the alert template 
ends with a series of pointers to items and controls inside the alert 
box. A long word of is used to indicate the end of the alert 
template. 

The following example creates a note alert. You can replace 
the NoteAlert function with either CautionAlert or StopAlert to dis- 
play a different icon as your own program requires. 

In machine language: 



DoNote 



anop 

pea 

pueblong 

pea 
pea 



toooo 

•Warning 

♦0000 

$0000 



iReault Space (Item ID) 
;AJert template pointer 
;711ter Pointer (use default) 
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-NoteAlert 










pla 






:get Hit Item ID 


evaluation of Item hit could be placed here 






its 








Warning 


dc 


i'60,30.110,290' 


dialog's rectangle 




dc 


T6374' 




;ID number (unique) 




dc 


b'81' 




:flrst stage alert 




dc 


h-ar 




;eecond stags 




dc 


trar 




Ithlri 




do 


b'81' 




ifourth 




do 


14'Lteml 


• 


;?lrst Item template 




dc 


14'ltem2 


' 


iSecond Item template 




do 


14-0000 




mull terminator 


lteml 


dc 


18'ooor 




litem id 




dc 


12'35,150.O0,00' 


display rectangle 




do 


12-10' 




itype = button 




do 


14'butl' 




litem descriptor 




dc 


12*0' 




lvalue of Item 




dc 


12*0' 




idefault bit vector 




dc 


WO' 




; default color table 


items 


dc 


12-6348' 




litem Id 




dc 


12'10,60,30,240' 


idlsplay rectangle 




dc 


18'IB' 




;type ■ text 




dc 


14'msgl 




litem descriptor 




dc 


IS'0' 








dc 


ISO' 








dc 


14 0" 






butl 


str 


'Okay 






msgl 


fltt 


This Lb 


a Note Alert' 




In 


C: 








ItemTempi&te lteml ■ 














ok, 


/" Hem Id 7 








36, 160. 0. 0. 


/* item rect ■/ 








buttonltem. 


/' Item type •/ 








'■ \ pOkay", 


f Item text •/ 


1; 






0, 0. NULL 


/" value, bit flag, oolor 

table'/ 


ItamTemplate ltem2 = 














6348. 


/■ Item Id ■/ 








10, BO. 30, 240, 


/• Item rest •/ 
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10' 




etatTeit, 


/■ Item type V 




" \ pTalB IB 8 


note alert", 


1. 


O. 0. NULL 


/• value, bit 

flag, and so on'/ 


}• 

AlertTempUte Warning = { 








BO, 30, 110. 290, 




6374. 


/• ID number (unique) '/ 




0181, 0X81. 


/• alert stages 1 and 2 •/ 




0X61. 0x81. 


/• alert Btagea 3 and 4 •/ 




frlteml. 


/' first Item template •/ 




*ltem2, 


/• second item template »/ 


): 

DoNotet ) 
i 


NULL 


f null terminator ■/ 






Int ItemHlt; 






ItemHlt = NoteAlert(*Warnlng, NULL): 
J 




i 

In Pascal: 






PROCEDURE DoNote; 






VAR Itaml : ltamTempUte; 






ltem2 : item Temp] ate; 






Warning ; AlertTemplate; 






ItemHlt : Integer; 






eutl : String; 






megl ; String; 






BEGIN 






bull :- 'Okay'; 






megl :— 'ThlB le a Note Alert' 






WITH Iteml DO BEGIN 






ItifflID:- l: 




{ item Id } 


SetReclUtemRect, 180, 3E 


. o. 0); 


■J Item root 1 


ItemType := Buttonltem 




1 Item type ) 


Item Descr : — CbUtl: 




• item text } 


ItemValue :- 0: 




{ value } 


ItemPl&g :— 0; 




{ bit flag 1 


ItemColor : — nil; 




{ color table j 


END; 






WITH ItemS DO BEGIN 






ItemID : - 834-8; 




{ item Id } 


SetRect(ItemRect, 60, 10 


240, 30); 


J Item reot } 


ItemType :«■ StatTextltem; 


! item type J 


IWmDeacr - Cmsgl; 




{ Item text ) 


ItemValue := 0; 




( value ; 
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:= 0; 
ItemColor = nil; 
END; 

WITH Warning DO BEGIN 

SetRect(atBoundBReot. 30, SO. 290, 110); 



bit flag ! 
color table 



atAIertID 

atStagel 

atSUga2 



atlt«mLlst(0] 
atItamLlet(l] 

atItemLlBt(3] 



= 6374; 
= *fll: 

- ttl; 
= 181; 

- t81; 
= ami; 
■ em2; 

- nil; 



first Item template ' 
second Item template 
null terminator 1 



END; 

ItemHlt := NoteAlertCPWamlng, all); 
END; 

Remember, in order to use l he types AlertTemplate, ItemTemplate, 
and so forth with older versions of TML Pascal, refer to the types 
defined in the "Important Pascal Notes" section earlier in this 

chapter, 

A Modeless Dialog Box 

Modeless dialog boxes are perhaps the least-understood type of di- 
alog box. Basically, a modeless dialog box is a cross between a win- 
dow and a dialog box. Unlike most dialog boxes, it can be dragged 
around, zoomed, and hidden behind other windows — all while still 
remaining active. 



Figure 10-2. A Modeless Dialog Box 



MODE-less 



This is a Modeless 
Dialog Boh! 



GUD 
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A good example of a modeless dialog would be a spelling 
checker in a desktop word processor. The modeless dialog can dis- 
play a misspelled word and offer a suggestion for the correct spell- 
ing. In response, you can edit the text in your document window, 
then click a Next button inside the modeless dialog box to go to 
the next misspelling. 

Because a modeless dialog box can be active along with every- 
thing else on the DeskTop, its events are not handled the same as 
those in modal dialog boxes. 

To handle a modeless dialog box, three separate routines need 
to be written: 

• The routine to create the dialog box 

• A modification to the TaskMaster call to detect activity inside the 
modeless dialog box 

• A routine to handle activity inside the modeless dialog box 

The routine to create the modeless dialog box works like the 
routine to create a modal dialog box (but without a template). All 
the information about the modeless dialog box is specified individ- 
ually, and then a call is made to the Dialog Manager's function 
NewModelessDialog. 

Items are placed into the dialog box, either via NewDItem or 
GetNewDItem, and then the function to create the modeless dialog 
box is complete. The events in the modeless dialog box are then 
picked up by TaskMaster, so once NewModelessDialog creates the 
dialog and places it on the screen, your program can go about its 
business. 

In order to monitor the events of the modeless dialog, you 
need to augment the TaskMaster call in your program's main scan- 
ning loop. After the TaskMaster call is made, your program should 
call the Dialog Manager's IsDialogEvent function. IsDialogEvent re- 
turns a logical TRUE value if a modeless dialog event has taken 
place. 

If a modeless dialog event has taken place, your program 
should branch to a routine to handle activity inside the modeless 
dialog. That routine calls the DialogSelect function with the ItemID 
of a control in the modeless dialog box. DialogSelect returns a logi- 
cal TRUE if that particular item has been selected (see the example 
below). 
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The following calls are used to create and manage a modeless 
dialog box: 



Dialog Manager Function 

NewModelessDialog 
NewDItem/GetNewDItern 
IsDialogEvent 
DialogSelect 



Action 

Creates the modeless dialog 
Places items into the modeless dialog 
Tests for a (modeless) dialog event 
Determines which item has been selected 



DRefCon 
DFullSizePtr 



To create a modeless dialog box, you need to define its size 
and location, as well as a title, frame description, and the other 
information you would use when defining a standard window. 

In order, NewModelessDialog uses the parameters listed in Ta- 
ble 10-11. 

Table 10-11. Parameters Used with NewModelessDialog 
Name Value Purpose 

DBoundsRectPtr Long A pointer to the dialog's rectangle 
DTitlePtr Long A pointer to a Pascal string for the title 

DBehindPtr Long Number of the window the dialog is behind 

DF3a S Word Bit pattern describing the dialog's frame 

Long Any value: User-defined value, usually 
Long A pointer to the size of the dialog when 
zoomed 

Many of these parameters have similar counterparts in the 
window record, most notably DBehindPtr, DFlag, and DRefCon. 

DBoundsRectPtr, DBoundsRectPtr is a long pointer to the ad- 
dress of a rectangle. The rectangle consists of four word values that 
define the size and location of the modeless dialog using global co- 
ordinates. As usual, the values are MinY, MinX, MaxY, and MaxX 
in that order (unless you're using TML Pascal, of course). 

DTitlePtr. The DTitlePtr is the long address of a Pascal string 
to be used as the modeless dialog box's title string. If DTitlePtr is a 
long word of 0, the modeless dialog box does not have a title. 

DBehindPtr. DBehindPtr acts tike wPlane in the window 
record. It indicates the position of the modeless dialog box in rela- 
tion to the other windows on the desktop, front to back. DBehindPtr 
is the value of the window behind which the modeless dialog box 
is placed. If a value of -1 ($FFFFFFFF) is used, the dialog box is 
put in front of everything else. 
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DFlae. DHag is a word-sized bit pattern describing the items 
in the modeless dialog's frame. The bit positions are exact y he 
<>ame as thev are for wFrame in the window record. Be sure to give 
your modeL dialog a title bar and don't specify scroll bars (dialog 
boxes do not have scrolling contents). A common value used for 
DFlag is $80A0, as seen in the example below. 

DRefCon. DRefCon, like wRefCon in the window record, can 
be anv lone word value you want it to be. 

DFullSizePtr. DFullSizePtr is a pointer to a rectangle that indi- 
cate, the size of your dialog box when zoomed. The DFlag ; option 
should specify a zoom box in your dialog's title bar ,n order for the 
coordinates pointed at by DFullSizePtr to have any effect. A long 
word of indicates that the zoomed size is the full screerv 

The following routines can be used to create a modeless dialog 
box on your desktop. The modeless dialog ^.^.^^ 
pulldown menu or by some other activity in the DeskTop. These 
routines are written for the 320-mode screen. 
In machine language: 

.long word result space 
;Blze/looatlon of modeless dialog 

ten 

;tltle of modeless dialog boi 
;place this window In front 
:wlndow frame bits 
;DPefCon - anything 
;Zoomed sue (not used) 

;teet for errors 
:get the pointer 



; dialog pointer 

;the ItemID, 1 *■ default button 

.reotangle pointer for the button 

:thie Item is a button 

,text inside button 

.Initial value 

;ltemPlag 

.color table 

.check for errors 



odeleBB anop 




pushlong 


♦10 


puehlong 


*MDBounds 


pushlong 


'MDTltte 


pushlong 


»*FPPfFr?F 


pushword 


*iaoAO 


puehlong 


•10 


pushlong 


MO 


_KewModelessDialof 


Jsr 


ErrChk 


pullloag 


ModelessPtr 


put an okay button Inside the hoi 


pushlong 


ModelessPtr 


pushword 


10001 


pushlong 


♦Button 


pushword 


»000A 


pushlong 


*Btn 


pushword 


10 


pushword 


10 


pushlong 


10 


_NewDItem 




Jw 


ErrChk 







— ^— Ofnlna firtvoc 








UlUIUg DUACi 




:put some ten In there too: 








pushlong 


ModelessPtr 


idl&log pointer 




pushword 


IFB02 


iltemlD 




pushlong 


TextReot 






pushword 


4600F 


.text Item + item disable 




pushlong 


*Teit 






pushword 


10 






pushword 


10 






pushlong 


to 






_ NewDItem 








Jar 


ErrChk 






its 


that's Iti All donel 




ModelessPtr 


ds 


4 


storage for modeless dialog 
:polnter 


MDBounds 


do 


L2'3Q,30.100.2QO' 




UDTltle 


str 


MODB-less' 




Button 


do 


I2'40.80,0,0' 




Bhrt 


str 


Neatl' 




TextReot 


do 


12"10,20.40,180' 




Text 


do 


U'endteit-starttexf 




startteit 


do 


c'Thls is a ModelessMl'13 






dc 


o' Dialog BoilMl'13' 




endtert 


atop 






InC: 









GrafPortPtr ModelessPtr; 
Reot MDBounda - [ 30. 30. 100. 200 
Reot BttnReot = • 40. 50. 0. ] ; 
Reot TextReot = f 10, 20, 40, 190 [; 

) 



ModelessPtr = NewMod8leeeDlalog(&MDBoundS, 

••xpMODB-lsss", topMost. Ol80aO. NULL. NULL); 
BrrChkt ): 
NewDItem (ModelessPtr, 1, tBttnRect. buttonltem, 

'•xpNeatr. 0, 0, NULL); 
BrrChk( ); 
NewDEU>m(ModelessPtr, OxPBQZ. fcTertRect. statText + ItemDlsable, 

"\pThle Is a Modeless \t Dialog Boilvr". 0. 0. NULL): 
BrrChkf ): 



In Pascal: 
PROCEDURE Modeless; 






220 



221 



[ 



Chapter 10 



VAfi ModelflsaPtr : WlndowPlr: 
MDBounds : Red: 
BttnHect : Reel; 

TextRect : Reel; 
Text : String; 
Btit : Swing; 



BUt :- 'Heatl'; 

Text := CQNCATOThls )8 a Model&Ba'. CHR(13). 

' Dialog Boil', CHR(13))l 
SetReot(MDBounde. 30. 30, 200, 100); 
SstHeot(BttnR«et, BO, 40, 0, 0); 
SatReetCTMtReot. 20. 10. 160, 40); 

ModelessPtT :- NewMod«l8ftBDlalog(MDBoundB. , M0DE-less\ 

WtndowPtrC-l).»80aO. 0. MDBcunda); 

BrrChfc 

NawItem(HodeleBBPtr. 1. BttnRect. Buttonltam, ffBtrt, 0, 0, nil); 

ErrCofc; 

NewDIwnKModelessPtr, IFS02, TeitReot. 3tatTeitItem+lwmDlsabla, 

ffTaxt. o.o, nil): 
ErrChk, 
End; 

After the above routines have been called, the modeless dialog 
box appears on your desktop. The window can be dragged about, 
just like any other window, but unlike a dialog box, you can pull 
down menus, open other windows, and perform other activities 
while the modeless dialog is visible. 

To monitor the events in the above modeless dialog, you need 
to modify your program's main scanning loop with the IsDialogEvent 
call. IsDialogEvent simply returns a logical TRUE or FALSE if the 
user has selected something in the modeless dialog. It requires only 
a pointer to the event record. 

The following routine shows how your program's main scan 
loop can be modified to handle a modeless dialog event, 

In machine language: 

Scan 



pha 




; result Space 


puebwQr-d 


•Iffff 


;event Mask 


puBalong 


•EventRec 


;polnt to Event Record 


_TaakMaeter 






pla 




;get task code 


beq 


Scan 


;lf nothing, continue looping 


asl 


a 


;double value la A 


tax 




:put In X tor reference 
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Jar 


(Table,!) 


;do the appropriate routine 


;now, test for a modeless dialog event 




pha 

PUShlQDg 

—IsDialogEvent 


'EventRec 


:one word result space 

;push the event record 


pla 

beq 
Jsr 


Scan 

MDEvent 


;get logical result 
;keep looping If FALSE 
otherwise, do the modeless 
:dlalog event 


bra 


Scan 


;keep scanning for events 


InC: 






while (IQFlag) | 




'" Walt for an event •/ 



do { 
Event = TaskMaater(0xrfff. &EventRec); 
\ while (lEvent); 

If (Event = = wlnMenuBar) DcMenu( ); 
If (IsDialogEvenK&EventHeo)) MDEventQ; 



In Pascal: 



REPEAT 
REPEAT 



{ Walt for an event } 
Event := TaBkMaater(*ffff, EventRec); 



UNTIL Event <> 0; 

IF Event = wlnMenuBar THEN DoMenu; 
IF iBDIalogEventCEventRec) THEN MDEvent: 
UNTIL QPlag: 

In the above routines, IsDialogEvent is called after the Task- 
Master call. If the result of IsDialogEvent is TRUE, the MDEvent 
routine is called. MDEvent contains a call to the Dialog Manager's 
DialogSelect function, the third routine used to monitor events in a 
modeless dialog box. 

When DialogSelect is called, your program can be certain that 
an event relating to your modeless dialog box has occurred. 
DialogSelect's job is to determine which control was selected with 
the mouse so that your program can act accordingly. DialogSelect 
requires the following parameters: 
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Name Value Purpose 

TheEventPtr Long A pointer to your event record 

TheDialogPtr Long A pointer to the dialog pointer 

ItemHitPtr Long A pointer to an ItemID 

There are quite a few pointers in this function. The actual val- 
ues are not passed to the DialogSelect function. Only the address 
of those values is handed down. 

The following is an example of a routine to handle the events 
inside a modeless dialog box. It would be called by the previous 
routine. 

In machine language: 

MDEvent a nop 



phs 

pushlong 
pu.Bh.toag 

pushlong 
_DlalogSalect 


*EventRec 
'DlalogPtr- 

'Hltltem 


;one word result space 

:push til© went record 

;address of dialog pointer 

;storage 

;polnter to bit item 


pla 

beq 


NoEvent 


;get logical result 
;leave It not our bit Item 


puehlong 
—Close Dialog 


ModBlesaPtf 


iclose this dialog cow 


NoEvent its 






DlalogPtr de 

Hitltem ds 


4 
3 




In C: 






MDEvent( ) 







GrafPortPtr DlalogPtr: 
Word ItemHlt; 

If (DlatogS*lect(&EventRec, SrDlalogPtr, *ItamHlt)) 1 

CloseDlalog(DlalogPtr); 

:■ 
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In Pascal: 

PROCEDURE MDEvent; 

VAR DlalogPtr : WindowPtr; 

ItemHlt : Integer; 
BEGIN 

IP DlalogSelect(EventRec. DlalogPtr, ItemHlt) THEN 
ClaaeDlalog(DlalogPtF); 
END; 

These routines test for only one item in the dialog box: item 1 
(the OK button). If the OK button is clicked, then the DialogSelect 
function returns a TRUE, and the dialog box is closed. Otherwise, 
DialogSelect returns FALSE and the program continues. 

Multiple DialogSelect calls would be required for a dialog box 
with more than one selectable control. For each item in the dialog 
box, a different call to DialogSelect would be made to determine 
whether that control was activated. (This is because DialogSelect 
returns only a TRUE or FALSE value, not an ItemHit as with the 
ModalDialog function and modal dialog boxes.) 

Pretty as an Icon 

In this section, and the remaining two sections of this chapter, ex- 
amples and techniques for modal dialog boxes are listed. You can 
incorporate these routines into your own dialog boxes. 

An icon is a graphic image you can place in your dialog box. It 
can be a symbol or logo, or it can be a switch to activate some 
event. However, unlike other types of controls, an icon needs some 
special adjustment to be placed into a dialog box. 



Actually, anything in a dialog box could be a switch. You sim- 
ply define that item without adding the item disable to it. The 
ModalDialog function returns that item's ItemID just as it 
would return the ItemID of a button, check box, radio button, 
or any other standard control. 
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Icons are defined as a series of bytes representing the pixels in 
the icon's image. They start with a rectangle indicating the size of 
the icon. The values in the rectangle are 

Offset Meaning 

+ $00 Offset of upper left Y coordinate 

+ $02 Offset of upper left X coordinate 

+ $04 Height of icon 

+ $06 Width of icon 

The height of the icon is the number ot pixels nigh the icon 
will be. The width of the icon is the number of pixels across. For 
the 640 mode, the width is double that of the 320 mode, even if 
the icon is of the same size. (The example below is for a 640-mode 
screen. For a 320-mode screen, the width value would be half of 
64, or 32.) 

If an icon is to be placed into a dialog box, it must be refer- 
enced via a memory handle. This creates a pointer to the icon's 
data. When you make the NewDItem call, the ItemDescr field be- 
comes the address of that pointer (the address of a pointer is tech- 
nically known as a handle). 

The three programs below are used to create and add an icon 
to a modal dialog box. (The icon design itself was created for the 
Living Legends Software company and appears in the About dia- 
logs of most of that company's Apple I1G5 software.) 

In machine language: 

De-Icon 



puahlong 


DlalogPtr 


;push the dialog pointer- 


push word 


•IF604 


;ltemiD for the Icon 


puahlong 


'IconRect 


; ree tangle for the icon 


push word 


'Iconltem 


;an Icon's ItemType, 112 


puahlong 


'IconPtr 


;handle (address of pointer) 
.to the icon 


pushword 


*0 


;Item Value 


pushword 


'0 


;Item Flag 


puahlong 


•0 


;oolor table 



IconFect 

loonPtr 
Icon 
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—inowi'iwmi 



do 
dl 
do 



BnObk 
l , 101,10,117,42' 

14'Icon' ;polnter to loon's data 

12'0.0. 16,64" ;slze of Icon following 

H'FFFFFFFFFOOOOOOFFOOOOOOOOOOOQFPF' 

H'FFFFFFFFOFPFFQFFOFFFFFFFFFFOFFFF 



w 








dc 


L/lUJug ooxes — ■ 

HFFFFFFF0FFFF0FPOFFFFFFFFFFOFFFFF' 






dc 


H'FFFFFPOPFFFOFFOOOOOuOOOOOOOOOOOP' 






do 


rfFFFPFOFPFFOFFFFFFFFFFPFFOFFFFOFF' 






dc 


H'FFFFOFFFFOFFFPPPFPFFFFFOFFFFOFFF' 






dc 


H'FFPOFFFFOFFFFFFFFFFFFFOFFFFOFFFF' 






dc 


H•FF0FFFF0FFFFFFFFFFPFP0FFFF0FFFFF• 






dc 


H'FOFFFFOFFFFFFPPFFFFFOFFFFOFFFFFF' 






do 


n'OOOOOOOOOOOOOOOOOFFOFFFFOFFPFFFP' 






dc 


H'PFFFOFFFFFFFFFFOFFOFPPPOFFFFFFFF' 






dc 


H ' FPF0FFFFFFFFF70FF0FFFF0FFFFFFFFF' 






dc 


H'FFOOOOOOOOOOOOFFOOOOOOPFFFPFFPPP' 






dc 


H'FFFFFFFFFFFFFFFFFFFFFPFFPFFFFFFF' 






dc 


H'7FFPFFFFFFFFFFFFFFFFFFPFFPFFFFFF' 






dc 


H'FFFFFFFFFFFFFFPFFFFFFFFPFFFPFFFF' 






InC: 






d»fln« 


fp oih 


' 




OBtUU 


P0 ouo 






deflu 


O.P OlOf 






ob*r Iooa[] = 


I 0. 0, 0. 0, 16, 0, 54, 0. /■ siM >j 






PP,FP.PP.PF,F0,00.00.0,F.P0,0a.00.0O,Q0,00,B.F,FF, /• data, v 






tr,yf.w.MW,n,?o,T?.q?,ft,??,n,TTMTT,rr. 








Ti,ff,?r.vQ.yT.Tr.nT,TQ.rr.77.?7.r?yy,w,?r,rr, 








F?.PF.y?,flP,FF,PO.FF.l»0.00,&O,00,00,00,O0.0O.QP, 








fp.ff.fo.pf.pf.o.f.ff.pp.ff.pp.ff.ff.qp.pp.fo.ff, 








r7.7r.q7.tt,ro,rr.Trjr.rr.rr.rr,7<}.77.77.qf,rt, 








rr.TQ.rr.rr.w,n,rT,T7,yy.T¥.T7,q7.ri',fo.yy l y?, 








rr.<ir.rr.ro.Tfyr.tT.rr.rT,fr,Yo.rr,rTMyjy.!y, 








To.7r,TY.qr,¥y.?t,!?.vT,r?jrMr.rr.rajT.y7.77. 








oo.oo.oo.oo.oo.oQ.oo.oo.qpj'o.Fp.pp.qp.FF.FP.pp. 








F?.PP,ftP.PP.Pf,FF,FF,F0.FF.()F 1 PP,PO,FP.PP.PP.PP, 






. 


PP.FO.FF.FF.FF.FP.??.QP,P0,PF,PP,a.F.FF,FF.FF.FF, 
FF,O0,00.00.O0,0O.00.W.0O,O0,0O.FF,FF.FF.FF.PF, 

FF,FF,FF.FF,FP,PF,FF,FF.FF.FF.FF.FF.FF,F?.FF,FF. 
FF.PF,FF,FF,FF.FF.FF.FF.FF.PF,FF,FF.FF.FF.FP,FF, 
FF.?F.FP.FP,FF.FF.PF,PF.FF.??.FP.FP.PF,FF,FF,FT 






Reel lconH«« = | 101. 10. 117, 42 \; 






DofconC ) 
I 








i 

Ptr iconPir — Icon; 








Xe*Dltom (DlalogPtr. 


teffl04, * loon Reel, laonlUm, 






*IoonPtr.O.O.qU; 
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In Pascal: 

PROCEDURE Doloon; 
VAR loonPtr : Ptr: 

IconRect : Raot; 

Icon : RECORD 

Bflect : Reot: 

Daw : ARRAY [0.18] OF 

PACKED ARRAY [1..1B] 0? Byte: 
END; 
BEQIN 

StftRactClcc-nfleol. 10. 101, 42, 117); 
SfltReot(Icon BReot, 0, 0, 64, 16); 

Stafffl6i(PIOOn.DaU[0). 'FFFFFFFFPOOOOOOFFOOOOOOOOOOOOFFF-): 
StUftH»l(P100n.Dftta(l). 'FFFFFFFFOFFFFOFFOFFFFFFFFFFOFFFF 1 ); 
8tUflH«Wcon.Data[2], 'FF?FFFFOPFFFOFFQPFFFFF?FFFOFFFFF•): 
StuflHei(«con.Data[3]. 'FFFFFFOFFFFOFFOOOOOOOOOOOOOOOOOP"): 
StuffHeiC*Ioon.DatA[4]. FFPFPQFFFFQFFFFFFFFPPPPFOPFFFOFP'); 
8tuflH«(«OMk.DMA{6]. 'FPFFQFFPFOPPFFFPPFFPPFFOFPFFOFFP'); 
SturfH8X(fl>l»n.DaW{6). •FPP0PFFFOFFFPFFFFFFFFF0FFFFOFFFF); 
8tuHH8lC#Icon-Iiala[7]. 'PFOFFFFOFFFFFFFPFFFFFOFFFPQFFFFF'); 
StuflHn(0Ioon.DBta(8], ■POFFFFOFFFFFFFFFFFFFOFFFFOFFFFFF); 

StufrH»»(l»IooD.D»U[0], ■OO00O0O0OOO0OOaO0PPO?FP?QP7FFFPP'); 

StTJffflex(0Icon.Dat&[lO],'FFFFOFFFFFFFFFFOFFOFFFFOFFFFFFFF-): 
8W{fHfl3i(*tiion.Data[ll],'FFF0FFFF7FFFFF0FF0FFFF0FFFFFFFFF'); 
Stufffl8x((SEoon.Datall2],'FF0O00O0000O0OFF000000FFPPPPPPPP'); 
8tuIfHax(ffIooC,Dftt«[ia],'FFFFFFFFPPPPPPPPFFPFFFFFFFFFFFFF'); 
3lUffH8X(»IC0n.D«tall4].-PPPP7FFFFTFFFFFFFFFFFFFFFFPPFFFF'); 
StUlffleiWcon.DataflBl.'FFFFFFFFFFFPFFFFFFFFFFFFFFFFFFFF 1 ): 

JeonPtr : - Moon; 

NairDItemCDIalogPtr. lfB04, IconRect. loonltem, PlwraPtt. 0. 0, nil); 
END; 

Some touch of compiler magic is required in both the C and 
Pascal examples. In the C example, to keep the icon data definition 
as brief as possible, some constants are defined to represent the 
hexadecimal values $00, $0F, $F0, and $FF. Also note that the 
icon's size parameters consist of eight characters rather than four 
word values because of the type of array defined. (A customized 
structure type could have been used to clean this up, however.) In 
Pascal, the StuffHex procedure, found in TML Pascal's ConsoIelO 
unit symbol file, is used to place hexadecimal data into the icon 
data buffer. Unlike C and machine language, Pascal does not allow 
you to define an array and have it filled with data at compile time. 
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Help 

Most DeskTop applications have a feature which provides helpful 
information about the program. A help dialog box may list special 
commands used in the program, or explain features that aren't in- 
tuitive. Suffice it to say that a help facility is standard equipment 
for most real-world applications. 

This chapter has already presented a number of examples 
showing how to display text and other information inside a dialog 
box. But what about changing existing information? For example, 
what if your help dialog box contained two or more pages of text? 
How would you switch between screens without creating new dia- 
log boxes for each one? 

It's done with two Dialog Manager functions, HideDItem and 
ShowDltem. When the visible flag is changed on text items, your 
dialog box can page through them, displaying one screen after an- 
other. If your help dialog has three screens of information, the last 
two are initially hidden, and only the first item is shown. When 
you go to the next page, perhaps by pressing a Continue button, 
the first item is hidden and the second item is made visible. 

With a little extra tweaking, you could even have buttons 
specifying Next Page and Previous Page. 

An About. . . Dialog Box 

Many chapters in this book have dealt with the MODEL program 
that was introduced in Chapter 6. This chapter caps off the MODEL 
program by putting an About. . . dialog box in the Apple menu. 
The following code examples can be used to put your stand- 
ard, run-of-the-mill About. . . dialog box into the MODEL program. 
This dialog box is rather boring. It only contains text and an OK 
button. You can add color, icons, or other features to your own dia- 
log boxes. However, when designing a dialog box, you should keep 
in mind the pointers offered in the Human Interface Guidelines 
(see Appendix A). While it would be nice simply to drop in the fol- 
lowing code as was done in the previous chapter, you will need to 
make several custom modifications to the MODEL program to fa- 
cilitate dialog boxes. Most importantly, you'll need to add the Dia- 
log Manager and LineEdit tool sets to the list of tool sets started 
and shut down by the program. 
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Once those tool sets have been started, you can replace the 
empty instruction for About. - . in the MODEL program with the 
following. To spice it up, you could experiment by adding your 
own custom icon. (Don't forget to insert the appropriate ShutDown 
function calls at the end of your program.) 

Program 10-1. Machine Language About, . . 






• dpple Menu: about 



About Dialog tan fF5<X» 

hit ton Item en. 

StatTcxt eau Mf 

ItemDisaole oqu *8000 

About p«» i ■ 

push long #(jial oqKeCOrd 
. GetNewrtoaai t'lal 09 
jsr ErrChl: 



sassign a value to this Dialog 

j id tor a Button 

lid tor static text 

idisaDl e an item 

8 long morO result space 



pul I long DiatoqF'tP 



sget dialog pointer 



;Mo» «sit until the Qi Button is el icM 



Wait 


D«f »'■'■'"■ 




;resu1 1 soace 




pea WC00 




!+ liter routine Hong pointer/ 




oea 1 








.nodal Dial 


09 


:9et dialog events 








sget results 




cnp »ri 




juas it tne Button ^ 




one wait 




Sleep waiting i* not 



Dialog Boxes 



;hs re done, close the dialog 



pusniong CiaiogPtr 
_ C I oseD 1 a 1 og 



rts 

uial ogrtr as 4 



[ii«i ogneiont eou 6j.> 
Oml oowidth 

tn » I 09 P>ee or anoo 

dc l2'U90-Dialogrteight)/2' 

dc i2' ia4< l -Iiialo9blidth»/2" 

dc i2 il90-Dialo9HeightJ/;«-[iis.logHeignt 

dc 1Z iMi.'-DLalogUidthi/ItCualogHidtri 

dc i2 rfiUE 

dc i4 

dc i«£"uttonRec 

dc i« TextFecord 

dc \4 



Pvttonhec dc i2 I 

ac 1 37,130,0,0 

or 12 &uttonIte»' 

ac 1* 8uttonte«t - 

dc 1; 

dc 1: 

oc i» 

Button Tewt str "Qlew Dolev" 



230 






231 



Chapter 10 



lertfcecora dc li^bouttiiiloo*: 

ac i NMO,B0.MO 

dc i2 ltenlnsable+StatTexf 

dc i4' TextStnn9 ' 

dc i. 

dc |2 

dc i4 ©' 

r«- tStnnq dc I I end ttMt -start text 

»t.rn..l dc e'Thll it » drmon i « r- » 1 1 on program for Advanced', 1 1 1: 

dc e' Programing T»dhnlqu«» «or the Appl* IIQS Tooibo. ,.1 13' 

end t pit *fep 



Program 10-2. C About. 



• mdd I e Weov 






friatoqwidtn 400 



tStnngn = 

"NpThll 11 • dimofmrilion proar am 4or •SdwtftetdNrS 

Proaramm.ng T«ehni qu*» for th» Appl* I 1 GS ToolboxNr 



ItBitilemol ate 1e/ 'Record = ( 



•*«>.>, 

ItMst'lsaOlel&t^tTe t . 
1e titring. 

HULL 



i • item J(I •/ 

• • item rect " 

/• item tvpe •/ 

/* item oescr-ictor •' 
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lte»iTe»pl ate Buttonftec = , 
o« . 

37. 130, <:>. 0, 
Kit ton I tea, 

" '■pOt ev Doi e. • ' ■ 
. . NULL 

j ; 



.' • item id •/ 

I • item rect •/ 

/« item type */ 

'• item t«t *' 

'• -.aiue, Pit flag, color tbl • / 



0>i a tog Temp late OiaiogKecord ■ < 

['lalogMeigh-- 
1 640- [i i a I ogw idth i / 2 , 
H90-Di»l<59Hei9tit '2*Di»Jo9He»9ht. 

-Dlf I ogWlOthr /2+Dial oqWldtn, 
TRUE. 
NULL, 

>-E<ut ton free, 
■rp-t Record, 

NULL 

n 

About < j 
( 

►rPdrtPtr DialogPtrs 

L'liiciqftr = GetNewflooal dialog I'.Dial oghecordi ; 
wmle ■ noda l [i l a 1 09 i NULL ■ '■ ok}; 
Cioseliialog i&iaiogPtr' ; 
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Program 10-3. Pascal About. . . 




In rascal : 




• upcie Menu: fttoout • 




» . ) 




RftOCEMJPE -oout; 




t'lalogrtr: W-inaOwF-tr: 




1e-t Record: 3te»Te»pl ate: 




cut. tonFec ; I temTenpl atei 




cshecord: In el oqlempl ate; 




But tOO ICKt! String; 




TextStnnsi string; 




BEG in 




ButtOnTe»t !■ 01 tv [i-i-e. : 




(String S" CONCATi Tflll ll » d«moft*tr*« ion program for Advanciil Proartnm'ng', 




1), T»cM>iqut« 'or the Appl» 1 1 65 Tool bo« ' , 




CHRll3>> 1 




WITH fiuttnnr.ee BO PE5IM 




ttatilD :- l: • it"> 'd » 




SetRect ilteo&ect, 130, 37, 0. Ml I ite« rect ) 




Itamfvpe := Kit ton Item: ( item tvpe 1 




ltenDescr := C-buttonText r < "ten te-t 1 




Upvalue !■ ■•: < value ) 




ItMFI*9 :- ! C hit «1AS ) 




IteiftLotop :* nil: < color cable ) 




ENi. : 
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[twiOHcr 


:* STextStrinq: 


ItemValue 


:= Ol 


ItemFlaq 


:= Ol 


Itemtolor 


:■ ml | 



WITH Te:tr-ecord DO BEGIN 

It en 3d :» : : ( ite» id ) 

SetRect ■ I tenner t, 10, 10, «4p, 60) I ( iten rect I 

Itenlvps :■ Ite«Di*5.ijle-fSt«tTeKt3tein: < item tvpe ! 

( item text » 

( value i 

( hit flag > 

I color taole > 
END: 

wllH OialogRecord 00 BEGIN 

SetRect cdtfioundsRect, 120, 65, S20, I25l | 

dtVisible : = TRUE? 

dtRefCon :» 0: 

dtLtemListll J :* eiestftecord i 
««Ite*ListC2] ;= nil ; 



CiialnejF-tp i= OetNewrladalfjial oq letiial ogR'ecordl ; 
REFEAI UNTIL MooalDial og mi l> = l; 
CI oset'ialoq tDidl ogFtr • : 



Chapter Summary 

The following tool set functions were referenced in this chapter. 

Function: $0215 

Name: DialogStartUp 

Starts the Dialog Manager 
Push: UserlD (W) 
Pull: Nothing 
Errors: None 
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Function: $0315 

Name: DialogShutDown 

Shuts down the Dialog Manager 

Push: Nothing 

Pull: Nothing 

Errors: None 

Function: 

Name: 



Push: 

Pull: 
Errors: 

Function; 

Name: 

Push: 

Pull: 

Errors: 

Function: 

Name: 

Push: 

Pull: 
Errors: 

Function: 

Name: 

Push: 



Pull 
Errors 

Function 
Name 



S0A15 

NewModalDialog 

Creates a modal dialog box 

Result Space (L); Rectangle Pointer (L); Visible Flag (W); 

DRefCon (L) 

Dialog Pointer (L) 

Possible Memory Manager errors 

S0B15 

NewMode lessD ia log 
Creates a modeless dialog box 

Result Space (L); Rectangle Pointer (L); Title Pointer (L); Win- 
dow Level (L); Frame (W); DRefCon (L); Zoomed Rect 
Pointer (L); 
Dialog Pointer IL) 
Possible Memory Manager errors 

$0C15 

CloseDialog 

Removes a dialog from the screen 

Dialog Pointer (L) 

Nothing 

Possible Window Manager errors 

SOD 15 

NewDItem 

Places a control into a dialog box 

Dialog Pointer (L); ItemlD (W); Rectangle pointer (L); 

ItemType (W); Item Descriptor (L); Item Value (W); Item Flag 

(W); Color Table Pointer (L) 

Nothing 

$150A, S150B 



S0F15 
ModalDialog 

Handles events in the frontmost dialog box 
Push: Result Space (W); Filter Procedure (L) 
Pull: Item Hit (W) 
Errors: $150D 
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Function: $1015 

Name: IsDialogEvent 

Determines whether an event is related to a modeless dialog 
box 
Push: Result Space (W); Event Record Pointer (L) 
Pull: Logical Result (W) 
Errors: None 

Function: $1115 

Name: DialogSelect 

Tests to see whether an item in a modeless dialog box was 
selected 
Push: Result Space (W); Event Record Pointer (L); Dialog Pointer 

(L); ItemlD Pointer (L) 
Pull; Logical Result (W) 
Errors: None 

Function: $1715 
Name: Alert 

Draws an "empty" alert box 
Push: Result Space (W), Alert Template (L); Fitter Procedure (L) 
Pull; Hem Hit (W) 
Errors: None 

Function: $1815 
Name: StopAlert 

Draws an alert box with a stop sign icon 
Push: Result Space (W); Alert Template (L); Filter Procedure (L) 
Pull: Item Hit (W) 
Errors: None 

Function: $1915 
Name: Note Alert 

Draws an alert box with a note icon 
Push; Result Space (W); Alert Template (L); Filter Procedure (L) 
Pull: Item Hit (W) 
Errors: None 

Function: S1A15 

Name; CautionAlert 

Draws an alert box with an exclamation point icon 
Push: Result Space (W), Alert Template (L); Filter Procedure (L) 
Pull: Item Hit (W) 
Errors: None 
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Function: 


$2215 


Name: 


HideDltem 




Hides a control in a dialog box, rendering it invisible 


Push: 


Dialog Pointer (L); ItemlD (W) 


Pull: 


Nothing 


Errors: 


$150C 


Function: 


$2315 


Name: 


ShowDltem 




Makes an item or control in a dialog box visible 


Push: 


Dialog Pointer (L): ItemlD (W) 


Pull: 


Nothing 


Errors: 


$150C 


Function: 


S2E15 


Name: 


GetDItemValue 




Returns the value (Item Value) of a control or item 


Push: 


Result Space (W); Dialog Pointer (L); ItemlD (W) 


Pull: 


Item Value (W) 


Errors: 


$150C 


Function: 


$2F15 


Name: 


SetDItem Value 




Changes the value of an item, or selects an item 


Push: 


New Item Value (W); Dialog Pointer (L); ItemlD (W) 


Pull: 


Nothing 


Errors: 


$150C 


Function: 


$3215 


Name: 


GetNewModal Dialog 




Creates a modal dialog using a template 


Push: 


Result Space (L); Template (L) 


Pull: 


Dialog Pointer (L) 


Enron; 


Possible Memory Manager errore 


Function: 


$3315 


Name: 


GetNewDltem 




Places an item or control into a dialog box using a template 


Push: 


Dialog Pointer (L); Template (L) 


Pull: 


Nothing 


Errors: 


$150A, S150B 


Window Manager Calls 


Function 


: $0C0E 


Name 


: Desktop 




Controls a variety of things dealing with the DeskTop 


Push 


: Result Space (L); Command (W); Parameter (L) 


Pull 


: Result (L) 


Errors 


: None 
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Function: 


$1D0E 


Name: 


TaskMaster 




Returns status of the event queue, updates window events 


Push: 


Result Space (W); Event Mask (W); Event Record (L) 


Pull: 


Extended Event Code (W) 


Errors; 


S0E03 


Memory M 


anager Calls 


Function; 


$0902 


Name: 


NewHandle 




Makes a block of memory available to your program 


Push: 


Result Space (L); Block Size (L); UserlD (W); Attributes (W); 




Address of Block (L) 


Pull: 


Block's Handle (L) 


Errors; 


$0201, $0204, $0207 


Function: 


$2002 


Name: 


HLock 




Locks and sets a specific handle to a purge level of 


Push: 


Handle (L) 


Pull: 


Nothing 


Errors: 


$0206 


Function: 


$2802 


Name: 


PtrToHand 




Copies a number of bytes from a specific memory address to 




a handle 


Push: 


Source Address (L); Destination Handle (L); Length (L) 


Pull: 


Nothing 


Errors: 


$0202, $0206 
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Controls are things you can put 
into dialog boxes or windows to 
perform specific functions. In 
addition, they have their own 
identities and allow a user to 
interact with a program using 
standards that are maintained 
in all Apple applications. 

The nicest part about con- 
trols, like just about everything 




Chapter 11 



else in the Toolbox, is that most of the work relating to them is 
done for you. You simply define the control, stick it in a window, 
and your work is done. When you consider that description, a 
chapter on controls might seem to be useless, Yet, there's a lot of 
information about controls that doesn't exactly fit under any other 
rubric. Hence, this chapter is full of information about controls. 

This chapter doesn't focus on the Control Manager, but instead 
concerns itself with the individual controls themselves. The chapter 
on the Dialog Manager gives dialog boxes a thorough going-over. 
But much more can be said about controls inside the dialog box. 
Therefore, this chapter has two areas of concentration: 

• The Control Manager 

• Controls 

The first part of this chapter provides some general infor- 
mation about the Control Manager (one of the more important tool 
sets). Then the chapter turns to techniques for customizing the 
standard controls already defined in the Toolbox so that they are 
best suited to your programs. At the end of this chapter you will 
find examples of the Control Manager being used to set or change 
the value of a control. 

The Control Manager 

The Control Manager is one of the more important, as well as ob- 
scure, tool sets. The following two tool sets rely upon the Control 
Manager in order to operate properly: 

• Window Manager 

• Dialog Manager 

The reason for this is that both of these tool sets use controls. 
All the items inside a window — the grow and zoom boxes and the 
scroll bars— as well as the items in a dialog box are controls. The 
Control Manager is the tool set whose job it is to manipulate those 
controls. You can choose from a list of predefined controls: buttons, 
radio buttons, check boxes, LineEdit boxes, and so on. Or, by using 
the Control Manager, you can create custom controls to use in your 
programs. 

Many of the functions of the Control Manager are called inter- 
nally by other tool sets. For example, the Window Manager must 
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access certain Control Manager functions to place the proper con- 
trols into a window. And when you set up a dialog box, it's the 
Control Manager that handles the intricacies of defining the con- 
trols and maintaining their values. As will be seen in a later section, 
many of the Dialog Manager's functions have similar, correspond- 
ing Control Manager functions, some of which are called internally 
by the Dialog Manager. 

Before you start the Control Manager, the following tool sets 
should already have been started: 

• Tool Locator 

• Memory Manager 

• Miscellaneous tool set 

• QuickDraw II 

• Event Manager 

• Window Manager 

To start the Control Manager the CtlStartUp call is made. 
You'll need to send the Toolbox your program's User ID, and set 
aside one page ($100 bytes) of direct page space. 

\n machine language: 

Us&r-ID 



pushword 
pushwo?d 

-CtlStartUp 

Jsr ErrChk 

In C: 



;pueh our user Id 

'.push direct page location 

;check for errors 



CtlStartUp(U8erID, GetDP(OxlOO)); BrrChkQ; 

In Pascal: 
CtlStartUp(UserID, GatDP(tlOO)); ErrChk; 

The GetDP call in the C and Pascal examples is described in 
the MODEL program, illustrated in Chapter 6. 

The only error being checked for after the CtlStartUp call is 
$1001, meaning the Window Manager has not been initialized. So 
when you're writing applications, it's a good idea to start up the 
Window Manager before the Control Manager. Also, as is true with 
all other tool sets, the Control Manager functions better if its allo- 
cated direct page space is page-aligned. (See the information on the 
NewHandle function in Chapter 7 for more information.) 



To shut down the Control Manager, a call is made to 
CtlShutDown. 

In machine language: 

_Ctl81iutDown 

In C: 
ctishutDownO: 

In Pascal: 
CtlShutDown; 

Be careful to shut down the Window Manager before making 
the above calls. If you're simply shutting down all the tool sets to 
quit a program, then the order isn't that crucial. Still, it's a good 
idea to shut down the Window Manager first. You may wonder 
why this practice is recommended. The reason is that the Window 
Manager is responsible for disposing of windows (and dialog 
boxes) containing controls. Therefore it's a good idea to shut it 
down first. This assures that there are no controls left on the screen 
when CtlShutDown is called. (CtlShutDown does not remove the 
controls, so when the Window Manager makes the call to the Con- 
trol Manager to remove the controls, an error results.) 

Shut down tool sets following the reverse of the order in 
which they were started up. 

Controls 

The Control Manager maintains several built-in controls. All the 
items in a window that manipulate the window are controls. Oth- 
ers managed by the Control Manager include the following items, 
which you can specify in a dialog box: 

• Buttons 

• Check boxes 

• Radio buttons 

• Scroll bars 

• Edit lines 

• Grow box 
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For each type of control there is a control record. This record 
contains information about the control: 

• The window to which it belongs 

• Pointers to its action procedure 

• Pointer to a color table 

It also contains information defined by your program when the 
control was initially put on the screen, or as maintained by the 
Control Manager as you are manipulating the control. 

The following sections detail each type of control. This infor- 
mation is provided to enhance information already presented in 
Chapter 10, For example, the following sections contain infor- 
mation about certain controls' I tern Value and ItemFlag, and how 
these values can be manipulated to give your programs their own 
unique look. Plus, there's information about changing the default 
color of a control, 

The following built-in controls can be specified as part of a di- 
alog box via the NewDItem or GetNewDItem calls of the Dialog 
Manager. NewDItem specifies each aspect of the control one at a 
time, whereas GetNewDItem uses a template of values. 

In summary, GetNewDItem sets up a call to NewDItem. 
NewDItem, on the other hand, contacts the Control Manager to set 
up the control. The Control Manager manipulates the information 
further and calls NewControl, which actually sets up the control 
record and assigns the control to a particular window, NewControl 
may do further initializing depending upon the type of control, 

Push button. Push buttons always perform some action, or 
they can activate something. Unlike other controls that can be 
switched on or off or positioned in some manner, when a push 
button is clicked by the mouse, it immediately causes something to 
happen (usually it closes a dialog box). 

Table 11-1 shows the items specified when a push button is 
defined. These items would either be individually specified via the 
NewDItem function, or using a template with the GetNewDItem 
function. 
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Table 11-1. 


Items Specified When Push Button Is Defined 


Name 


Size 


Buttonltem Value 


ItemID 


Word 


The button's ID 


Item Re ct 


Word 


Upper left Y position of the button (MinY) 




Word 


Upper left X position of the button (MinX) 




Word 


Usually 




Word 


Usually 


Item Type 


Word 


S000A (10 decimal) 


llemDescr 


Long 


Pointer to string inside the button 


Item Value 


Word 


Always 


ItemFlag 


Word 


Determines visibility and type of button 


ItemColor 


Pointer 


A table defining the button's color 



ItemID. ItemID assigns a unique value to the button. A value 
of $0001 defines the button as the default button of the dialog box. 
The default button has a double outline. Pressing Return is the 
same as clicking the default button. 

An ItemID of $0002 defines the default Cancel button, which 
is equivalent to pressing the Escape key. Other values can be used 
simply to define a typical push button. 

ItemRect, The ItemRect of the button defines its location and 
size relative to the upper left corner of the dialog box (position 0,0). 
Normally, only the first two words of this rectangle are specified; 
the last two can be zeros. The Control Manager will fill in the 
other corner based on the size of the text inside the button. 

Later in this chapter, an example of a button is shown with all 
four values defined. Even though the second two words need not 
be actual values, the Control Manager will still create a push but- 
ton (though of a nonstandard size), and will still center the text 

within that button, 
witnin mat outton. 

ItemType. The ItemType for a button is $000A, or 10 decimal. 



Instead of using a raw number, check your language's support 
files for predefined symbol names that can greatly improve the 
readability of your program. For example, when you include 
the <dialog.h> header file in your C programs, you can use 
the defined constant called buttonltem rather than the number 
0x000a (hex) or 10 (decimal). 
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JtemDescr. ItemDescr is a long-word pointer to the string to be 
placed inside the button. The string should be rather short, as any- 
thing longer than one or two words is considered an essay. When 
that's the case you should consider whether the button is appropri- 
ate. The button's string should start with a count byte (a Pascal 
string). 

UemValue. Item Value should always be a word of 0. A button 
does not require an item value. 

HemFlag. ItemFlag is a word describing whether the button will 
be visible or invisible, and it also determines what type of frame 
the button will have. Only the LSB (lower byte) of this word holds 
any value; the upper byte should always be 0. 

Bit 7 of the ItemFlag word determines the visibility of the but- 
ton. When bit 7 is set to 1 (a value of $0080), the button is invisi- 
ble. When bit 7 is reset to 0, the button is visible. There are Dialog 
Manager and Control Manager functions that will change a but- 
ton's visibility after it has been created. (Note that there is a differ- 
ence between a visible button and one that is disabled. See below.) 

Bits and 1 of ItemFlag determine the style of the button's 
frame, or outline. Buttons can have square or round comers, and 
they can have a double outline or a drop shadow, all depending on 
how these bits are set. 



Table 11-2. Style of Button's Frame 
Bit 



1 





Hex Value 








$0000 





1 


$0001 


1 





$0002 


1 


1 


$0003 



Meaning 

Typical round -cornered button 

Round -cornered button with double border 

Square button 

Square button with a drop shadow 



Figure 11-1. The Four Types of Buttons 
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The default button for a dialog box uses a bit pattern of $0001. 
Other bit patterns for ItemFlag can be used to create different- 
shaped buttons. However, Apple advises against using the double- 
border pattern ($0001) on buttons other than the default button. 

ItemColor. ItemColor is a long-word pointer to a color table for 
the button, The color table can be used to specify colors other than 
black and white for the button's parts. For example, the button's 
text could be green on pink and the button could be gray on blue. 

Table 11-3 describes the color table used for a push button 
(and pointed to by ItemColor). 

Table 11-3. Push Button Color Table 
Offset Size Parameter Bits 

$00 
$02 
$04 
$06 
$08 

OUT - Outline color 
BG — Background color 
FG — Foreground color 
■ Always lero 

The individual bit positions in each word of the color table are 
used to specify which colors are used to color each part of the but- 
ton. In the 320 mode, all four bit positions (7-4 or 3-0) are used to 
specify one of 16 different colors. In the 640 mode, only bits 4 and 
5, or bits and 1, are used to specify color. Be careful to note 
which values of the word (bitwise) are used and which aren't. 

SimpOutline. SimpOutline describes the color of the button's 
outline. 

SimpNorBack. SimpNorBack is the background color of the 
button when the button is not being pressed, 

SimpSelBack, SimpSelBack is the background color of the but- 
ton when the button is being pressed. 

SimpNorText. SimpNorText is the color of any text inside the 
button when the button is not being pressed. The background color 
of the text is specified in bits 7-4 and the foreground color in bits 
3-0. 







15-8 


7-4 


3-0 


Word 


SimpOutline 





OUT 





Word 


SimpNorBack 





BG 





Word 


SimpSelBack 





BG 





Word 


SimpNorText 





BG 


FG 


Word 


SimpSelText 





BG 


FG 
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SimpSelText. SimpSelText is the color of any text inside the 
button when the button is being pressed. The background color of 
the text is specified in bits 7-4 and the foreground color in bits 3-0. 

The following creates a rather interesting colored button (in 
320 mode). You might want to include a color table such as this 
with a program that uses the colorful menu bar example from 
Chapter 8. 



ButtonColofT dc 


18 4 %00000000001 10000 


dc 


12'1fr0000000001010000 


do 


12-960O0OOO0O11010000 


dc 


12-*0000000001110110 


dc 


12'%0000000010001001 



Notice how similar this is to setting the color table for a win- 
dow as described in Chapter 9. 

Check box. A check box represents a condition, either on or 
off. Clicking in a check box doesn't automatically turn it on, or acti- 
vate it. Instead, its Item Value must be changed either through the 
SetDltem Value call in the Dialog Manager, or via Control Manager 
calls as outlined in a later section of this chapter. (This was covered 
briefly in the previous chapter.) When you click the mouse in a 
check box, it should become checked if it wasn't already, or it 
should become unchecked if it was. This logic is supplied by your 
program. 

Check boxes have a line of text beside them. Unlike static text 
items, the text by a check box is defined along with other attributes 
of the check box. Therefore, the position of the check box on the 
screen should account for any text just to the right of it. 

Table 11-4 shows the values used to define a check box: 

Table 11-4. Values Used to Define a Check Box 

Checkltem Value 

The check box's ID 

Upper left Y position of the check box (MinY) 

Upper left X position of the check box (MinX) 

Zero 

Zero 

$000B(11 decimal) 

Pointer to check box's title string 

$0000 for open, any other value for selected 

Determines visibility 

A table defining the box's color 



Name 


Size 


ItemID 


Word 


ItemRect 


Word 




Word 




Word 




Word 


ItemType 


Word 


ItemDescr 


Long 


I tern Value 


Word 


ItemFlag 


Word 


Item Col or 


Pointer 
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ItemID. The ItemID of a check box can be any value used to 
identify the checkbox uniquely. You could specify an ItemID of 
$0001 or $0002; it isn't recommended, however. This would clash 
with the rules set down in Apple's Human Interface Guidelines. 
Only a push button should be the default button in a dialog box, 
so only a push button should have an ItemID of $0001 or $0002. 

ItemRect. ItemRect, like a button, defines the location of the 
check box relative to the upper left corner of the dialog box. Any 
text appearing next to the check box will be to the right of the 
check box. As with a button, keep the text brief. 

ItemType. The ItemType of a check box is $000B, or 11 
decimal. 

ItemDescr. ItemDescr is a long-word pointer to the string ap- 
pearing next to the check box. The string should start with a count 
byte. 

ItemValue. Item Value indicates the initial value of the check 
box. If ItemValue is 0, the check box is empty, or unchecked. If 
ItemValue is any nonzero value, the check box is checked, indicat- 
ing that whatever state the check box is monitoring is presently se- 
lected, or active. 

ItemFlag. A check box's ItemFlag holds the same meaning that 
it does for a push button: It determines whether the check box will 
be visible or invisible. A value of $0080 means the check box will 
be invisible, while a value of $0000 means the check box will be 
visible. 

ItemColor. ItemColor is a long-word pointer to a color table for 
the check box. Table 11-5 describes the items in a check box's color 
table. 

Table 11-5. Items in Check Box's Color Table 



Offset Size 


Parameter 




Bits 








15-8 


7-4 


3-0 


$00 Word 
$02 Word 
$04 Word 
S06 Word 


CheckReserved 
CheckNorColor 
CheckSelColor 
CheckTitleColor 










BG 
BG 
BG 




FG 
FC 
FG 


BC ~ Background 
FC - Foreground 
D = Always zero 


cotor 

color 
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The same information for a push button's color table (regard- 
ing bit positions) holds true for this and all succeeding color tables. 
Remember that the 320 mode is much more colorful than the 640 
mode. 

CheckReserved. CheckReserved should be a word of 0. Pre- 
sumably Apple has something clever in mind for this value and 
just won't let us know what it means. 

CheckNorColor. CheckNorColor is the color of the check box 
when it's not highlighted or selected. 

CheckSelCalor. CheckSelColor is the color of the check box 
when it's highlighted or selected. An example of color usage would 
be to specify bits 7-4 to show a different color (say, red) for a se- 
lected check box. 

CheckTitleColor. CheckTitleColor is the background and fore- 
ground color of the check box's title string at all times. (The title 
does not change as the box changes.) 

Radio button. Radio buttons are among the most useful types 
of controls. Yet they are also easily misunderstood. With radio but- 
tons, only one in a series can be selected at a time — and one of the 
series must be on. Figure 11-2 gives an example of a good use for 
radio buttons. 



Figure 11-2. Row of Three Radio Buttons: Up, Down, and From Top 



Search Direc 


tion: 


O UP 




® Down 




O From 


Top 


(Cancel] 


(( 0ka y ] 
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Why call them radio buttons? The analogy Apple gives is that 
of an old car radio. The buttons on the radio were used to 
switch from one preselected radio station to another. Only one 
of the buttons could be down at a time — you couldn't listen to 
more than one station. When you pushed one in, any other 
button that was pressed in would be automatically released. 

Radio buttons should be used in an application when one 
of several options must be selected, but not more than one. If 
it's possible to choose more than one option, check boxes 
should be used. 



You can specify which radio button is to be on when the dia- 
log box is created. However, as with other items in a dialog box, 
further manipulation of the radio buttons is up to your program. 
(Refer to the COLOR program from Chapter 10 for a good example 
of radio button manipulation.) 

Table 11-6 shows the values used to define a radio button. 

Table 11-6. Values Used to Define Radio Buttons 

Radioltem Value 

The radio button's ID 

Upper left Y position of the button (MinY) 

Upper left X position of the button (MinX) 

Zero 

Zero 

S0OOC (12 decimal) 

Pointer to radio button's title string 

$0000 for open, any other value for selected 

Determines visibility and family number 

A table defining the button's color 

ItemlD. The ItemlD of a radio button, as with a check box, can 
be any value except $0001 or $0002. A family number can be given 
to a radio button via its ItemFlag value. This family number is used 
to group radio buttons according to their function, and to ensure 
that only one radio button within a particular family is on at a 
time. (The Control Manager will actually prevent you from activat- 
ing more than one radio button at a time. See the ItemFlag descrip- 
tion below.) 



Name 


Size 


ItemlD 


Word 


Item Red 


Word 




Word 




Word 




Word 


li em Type 


Word 


ItemDescr 


Long 


Item Value 


Word 


ItemFlag 


Word 


ItemColor 


Pointer 
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ItemRect, ItemRect defines the radio button's location relative 
to the upper left corner of the dialog box. Any text appearing next 
to the radio button will be to its right. 

ItemType. The radio button ItemType is $000C, or 12 decimal. 

ItemDescr. ItemDescr is a long-word pointer to a Pascal string 
to appear next to the radio button. 

ItemValue. item Value indicates the initial value of the radio 
button. As with a check box, when ItemValue is 0, the radio button 
is unselected, and when ItemValue is any nonzero value, the radio 
button is highlighted. 

ItemFlag. ItemFlag determines the visibility of the radio button 
as well as its family number. Bit 7 of the ItemFlag word determines 
visibility. When this bit is set to 1, the radio button is invisible; 
when bit 7 is reset to 0, the radio button is visible. The remainder 
of the bits in this word (bits 6-0) specify the family number of the 
button. Values in the range $0000-$007F can be used for up to 128 
family numbers. 

ItemColor. ItemColor is a long word pointer to a color table for 
the radio button. 

Table 11-7, Meaning of Bits Within ItemColor 



Offset Size Parameter 




Bits 




$00 Word RadioReserved 
$02 Word RadioNorColor 
$04 Word RadioSelCofor 
$06 Word RadioTitleCoIor 


15-8 






7-4 


BG 
BG 
BG 


3-0 


FG 
FG 
FG 


BG ■ Background color 
FG — Foreground color 
Always zero 









RadioReserved, RadioReserved is a word of 0, reserved for 
some future date. Perhaps Apple will design a three-dimensional 
radio button selected with this value, 

RadioNorColor. RadioNorColor is the color of the radio but- 
ton when it's not highlighted or selected. 

RadioSetColor. RadioSelColor is the color of the radio button 
when it is highlighted or selected. 

RadioTitleCoIor. RadioTitleCoIor is the background and fore- 
ground color of the radio button's title string. 



Scroll bar. You may not think of scroll bars as controls, but 
they are. They're just like buttons, check boxes, and radio buttons. 
They're usually used with windows. However, they can be used for 
other purposes if you know how to manipulate them. 

Figure 11-3. Diagram of Scroll Bar with Associated Terms 

Up Arrow & 



Thumb — 

Page Region — 
Down Arrow — 



L«ft Arrow Thumb Page Region 

K>['-' 'I 1 ' 



o 



Page Region 



Right Arrow 



The scroll bar is the most complex type of control you can de- 
fine. The Window Manager uses scroll bars in windows to scroll an 
area of data. However, if you want to put a scroll bar into a dialog 
box just to see what it's like, you'll need to know the information 
provided by Table 11-8. 

Table 11-8, Information Required to Define a Scroll Bar 

ScrollBarltem Value 
The scroll bar's ID 

Upper left Y position of the scroll bar (MinY) 
Upper left X position of the scroll bar (MinX) 
Lower right Y position of the scroll bar (MaxY) 
Lower right X position of the scroll bar (MaxX) 
S0O0D (13 decimal) 

Zero, or a pointer to an action procedure 
Data size minus view size (greater than 0) 
Determines visibility and scroll bar items 
A table defining the scroll bar's color 

[temlD. ItemlD i§ a value used to identify the seell bar : 

UemRect. ItemRect defines the scroll bar's location in the dialog 



Name 


Size 


ItemID 


Word 


ItemRect 


Word 




Word 




Word 




Word 


ItemType 


Word 


ItemDescr 


Long 


Rem Value 


Word 


ItemFlag 


Word 


ItemColor 


Pointer 
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box (or window), relative to the dialog box's upper left corner (local 
coordinates). The two words indicating the lower right corner of 
the scroll bar take on significance here and must be specified. To- 
gether the four word values create the rectangle into which the 
Control Manager will squeeze the scroll bar. 

By adjusting the corner positions of the scroll bar, you can 
have a very skinny scroll bar, or one that's terribly fat. Because a 
scroll bar is a predefined control, you can subtly change the way it 
looks to use it as a custom control in your programs, 

HemType. The ItemType of a scroll bar is $000D, or 13 
decimal. 

ItemDescr. itemDescr is the long-word address of a scroll bar 
action procedure used to control the scroll bar. A long word of 
can be used to specify the default procedure. 

ItemValue. ItemValue indicates the position of the thumb in the 
scroll bar. The higher the value, the further along in position the 
thumb will be (with the origin at the top or far left of the scroll bar, 
depending upon the scroll bar's orientation). 

ItemFlag. ItemFlag determines the visibility of the scroll bar, as 
well as the orientation of the scroll bar and what types of arrows it 
will have. (The thumb and page regions of the scroll bar are in- 
cluded standard, but the up/down or right/left arrows are consid- 
ered optional.) As with other ItemFlag values, only bits 7 through 
hold any significant value in this word. All other bits should be re- 
set to 0.' 

Table 11-9 shows the meanings of the bit positions in a scroll 
bar's ItemFlag. 

Table 11-9. Meaning of Bit Positions in Scroll Bar's ItemFlag 

Bit Meaning if Set 

7 Scroll bar is invisible 

6 Nothing (should always be 0) 

5 Nothing (should always be 0) 

4 Scroll bar is horizontal (right to left) 

3 Scroll bar will have a right arrow 

2 Scroll bar will have a left arrow 

1 Scroll bar will have a down arrow 

Scroll bar will have an up arrow 
If bit 4 above is reset to 0. the scroll bar will be vertical, or up and down. 
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You can specify arrows either in one or both directions (up/ 
down, left/right) for your scroll bar. It's possible to specify a 
left/right arrow with an up/down scroll bar, even though it's 
wrong, Your program will not crash, but the scroll bar will be up- 
dated improperly and your dialog box will fill with random graph- 
ics. In other words, it's ill-advised. 

So, to specify a full-on vertical scroll bar with both arrows, an 
ItemFlag of $0003 is used. For a full-on horizontal scroll bar, an 
ItemFlag of $001C can be used. 

ItemCotor. ItemColor is a long word pointer to the scroll bar's 
color table as shown below. 

Table 11-10. Meaning of Bits Within ItemColor 



Offset Size 


Parameter 




Bits 










15-8 


7-4 


3-0 


$00 


Word 


ScrollOutline 





OUT 





$02 


Word 


ArrowNorColor 





BG 


FG 


$04 


Word 


ArrowSelColor 





BG 


FG 


$06 


Word 


ArrowBackColor 





BG 





$08 


Word 


Thum b NorColor 





BG 





$0A 


Word 


ScrollReserved 











$0C 


Word 


PageRgnColor 


PAT 


COL1 


COL2 


$0E 


Word 


InactiveColor 





BG 





OUT 


- Outline color 








BC = 


Background 


color 








FG - 


Foreground 


color 








PAT- 


Color pattern 








- Always zero 











ScrollOutline, ScrollOutline is the outline color of the scroll 
bar, arrow boxes, and thumb. 

ArroivNorColor. ArrowNorColor is the color of the arrow out- 
line and background when an arrow is not being selected by the 
mouse. 

ArrowSelColor. ArrowSelColor is the color of the arrow 
(filled) and background when the arrow is selected by the mouse. 
A good method of setting this and the previous color value is to 
reverse them: Use the foreground color for ArrowNorColor and the 
background color for ArrowSelColor, and vice versa. 

ArrmvBackColor. ArrowBackColor is the interior color of the 
arrow when it is not selected. 

ThumbN or Color. ThumbNorColor is the color of the thumb's 

interior. 
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ScrollReserved. ScroilReserved is a word of 0, reserved for 
some secret future use, 

PageRgnColor. PageRgnColor is the color of the page region 
in the scroll bar. The MSB of this word determines whether a dith- 
ered pattern is to be used. The LSB of the word contains either the 
solid color with which to fill the page region, or two colors to use 
for dithering. 

If bit 8 is set, dithering takes place. The page region is filled 
with a checked pattern of both the colors specified in bits 7-4 and 
3-0. 

If bit 8 is reset to 0, the page region is filled with the solid 
color pattern indicated by the color specified in bits 7-4. Bits 3-0 
should all be reset to 0. 

Bits 15-9 of the PageRgnColor value should always be 0. 

InactiveColor. InactiveColor is the color of the scroll bar when 
it has been deactivated (dimmed). 

Edit lines. Edit lines are controls that allow a user to type a 
line of text into a dialog box. Edit lines are best used when the 
information needed by your program cannot be obtained by using 
a button or list of items. 

Any text typed at the keyboard will appear in the edit box. 
Additionally, because of the LineEdit tool set, the text inside the 
edit line can be edited, selected with the mouse, cut, pasted, de- 
leted, or copied to a special edit line clipboard (maintained by the 
Toolbox) using the standard editing keys. (See Appendix A for 
more on editing.) 

Any key pressed will appear in the edit line. When Return is 
pressed, the default button of the dialog takes over and the dialog 
box vanishes. Because of this, if more than one edit line appears in 
a dialog box, the Tab key is pressed to switch between one edit 
line item and another, If a number of edit lines are in a single dia- 
log box, the Tab key can be pressed repeatedly until the insert 
cursor is in the desired edit line. 

If a default button is not defined, the Return character (an in- 
verse question mark in the system font, or simply a blank) is dis- 
played in the edit line just like any other character. 

The first edit line defined, either by the NewDltem or 
GetNewDttem functions or first in a template of items for the 
GetNewModalDialog call, is the first edit line created and placed 
into the dialog. The cursor appears in the first defined edit line box. 
The ItemID of the edit line has nothing to do with its order. 
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ItemID 


Word 


ItemRect 


Word 




Word 




Word 




Word 


ItemType 


Word 


ItemDescr 


Long 


ItemValue 


Word 


ItemFlag 


Word 


ItemColor 


Pointer 



The items listed in Table 11-1 are used to define an edit line. 
Table 11-11. Information Required to Define an Edit Line 

Edit Line Value 

The EditLine's ID 

Upper left Y value of EditLine's box (MinY) 

Upper left X value of EditLine's box (MinX) 

Lower right Y value of EditLine's box (MaxY) 

Lower right X value of EditLine's box (MaxX) 

$0011 (17 decimal) 

Pointer to string inside the EditLine, or buffer 

Max characters to be typed (up to 255) 

Determines visibility 

Always 

ItemiD. The ItemID is a unique number used to identify the 
edit line. Its value is really unimportant because editing and enter- 
ing text takes place automatically. 

ItemRect. ItemRect defines a rectangle indicating the size and 
position of the edit line's input box in local coordinates. The length 
of the box (left to right) depends on the number of characters the 
user should be allowed to enter (and, indirectly, depends on the 
system font as well), The height of the box must be at least 15 
pixels — anything less and text inside the edit line will not be 
visible. 

The height of the edit line's box really depends on the size of 
the font used by the Dialog Box. For a smaller font, logically, a box 
of less than 15 pixels in height could be used. Likewise, if an ex- 
ceptionally large font were being used, a height taller than 15 
pixels would be required, 

ItemType- The ItemType for an edit line is $0011, or 17 
decimal. 

ItemDescr. ItemDescr points to either a string of text that may 
be edited, or an empty buffer into which typed text will be placed. 
ItemDescr must point to something, either an empty buffer or a 
string of text. If ItemDescr is the address of a Pascal string of text, 
that text appears as selected when the Control Manager draws the 
edit line, 

ItemValue. ItemValue determines how many characters are al- 
lowed inside the edit line, Only the number of characters specified 
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by ItemValue can be typed into the edit line, and no more. Item- 
Value also indirectly indicates the size of the string pointed to by 
ItemDescr. 

ItemFlag, ItemFlag can be one of two values. When Itemflag is 
$0080, the edit tine's box is invisible, but the text can still be seen. 
When ItemFlag is 0, EditLine's box is drawn. 

The edit line control does not use a color table, so its value 
should be reset to a long word of 0. 

Changing Colors 

Almost every control can take advantage of color. Your dialog 
boxes can be made colorful simply by specifying a color table 
pointer and filling the table with the desired values for each con- 
trol. But some confusion can arise in referring to color tables as 
used by controls and color tables used by QuickDraw. 

It should be pointed out that the color tables used when defin- 
ing a control are the same as the color tables used by QuickDraw. 

QuickDraw defines a color table from which certain colors are 
selected. For example, in the 320 mode, QuickDraw sets up a color 
table with 16 separate colors. Each color is defined according to the 
intensity of its red, green, and blue attributes. So, in a QuickDraw 
color table, color number 5 in that table may be set to dark green. 

In the color tables used by controls, the values referred to are 
the values in the QuickDraw color tables. So if the current color ta- 
ble as used by QuickDraw has 16 values and number 5 is dark 
green, then when you specify a value of 5 in your control table, it 
takes on the color dark green. In fact, all the pixels on the super- 
high-resolution graphics display on the Apple IlGS work this way: 
They aren't fixed color values; they're simply index numbers into a 
color table. 

Table 11-12 shows how QuickDraw assigns color values in the 
standard 320-mode color table. The control value and color indicate 
the value specified in a control's color table and the color that 
value represents. Use this table to determine which values in your 
control's color tables will take on which colors (using the standard 
color table in the 320 mode). 



Table 11-12. Color Values 
QuickDraw Number Color 



Control Value 
Binary Hexadecimal 






Black 


0000 


$0 


1 


Dark gray 


0001 


$1 


2 


Brown 


0010 


$2 


3 


Purple 


0011 


$3 


4 


Blue 


0100 


$4 


5 


Dark green 


0101 


$5 


6 


Orange 


0110 


$6 


7 


Red 


0111 


$7 


8 


Beige 


1000 


$8 


9 


Yellow 


1001 


$9 


10 


Green 


1010 


$A 


11 


Light blue 


1011 


SB 


12 


Lilac 


3100 


$C 


13 


Periwinkle 


1101 


$D 


14 


Light gray 


1110 


SE 


15 


White 


1111 


$F 



A control's color table can be changed or altered to suit your 
personal tastes and whatever is in vogue. 

Panic Button 

The following code (Programs 11-1 to 11-3) shows how a push 

is size and color can be manipulated to create a very large 
panic button. These examples are not complete programs. The code 
represents a panic button subroutine (to be called at the appropri- 
ate time) that you can place into your own programs. 

Program 11-1. Panic Button in Machine Language 



- PANIC Button 


dialog 


Box 


: Equates.. . 

luaiogtwignt 
BiaioqWidth 

ItemLfjsaeii* 
StatTexs 

But ton a en 


*qu 
eau 
equ 
equ 


100 

110 

»BO0O 

•OF 

•OA 



:Start ot Routine... 
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_ 



Gonfrojs — ^-^-^— ^^^^—~ 


Panic ph •OQOQ : long word result space 




pea MOOO 




push long »DialogReeord 




J3>tNM)HO0«JDl«Ioo 




JSf ErrCSk 




Pull long DialogPtr ;get dialog pointer 




;Ncv wait until the Button is clicked 




Wait pea »0000 : result space 




pea SO0O0 ;f liter routine t long pointer? 




pea SQOOQ 




Jtotfal Dialog :get dialog events 




pla suet results 




**" **' :«« it the panic button? 




bnf tf4l{ Jkeep waiting if not 




pusnlong DialogPtr ;we re done, close the dialog 




jCloseDj aloe 




rts ireturn, done 




j Data Storage 




DialogPtr as 4 




DiaiogPecoro anop 




dc i2'C190-DialogHeight)/2' 




be l2'C320-DialogWidth)/2' 




Oc i2'C190-DlalogHeightV2*DlalogKeight' 




dc l2'(320-0ialoflWideh)/2+Dia[t^w,dth 




dc 12' TRUE' 




dc I4'0' 




dc H'TextRecord' 




dc MButtonRecord- 




dc M'O' 




Text Record anop 




dc i2'2' 




dc k'S.B.lS.IOS' 




dc i2'ltemDl3*Dle«StatText' 




dc i4'TextStnng- 




dc \2'0' 




<JC 120 




ac i4'0' 




rextStrmg anop 




dc ll'IS' 




OC Cits time to...* 




But ton Record anop 




dc |2| 




dc i'2S. 5,95,105' 




dc 12' Button! tem' 




dc i4'8uttonStnng- 




ac 12'0' 




dc t2»0' 




dc i4 ColorTable' 
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fluttonStrtng 
str 


anop 
Panic 




Col orTable 
Oc 
dc 
dc 
ac 
dc 


anop 
12'ttOOOOOODOlOlQOOO' 

12'WOOOOOOOIHlOOOO' 
iS'KOOOOOOOOOl 110000- 
i2'\OOQ000001H 10000' 
l2'*00000OOO0H 10000' 




Program 11-2. 


Panic Button in C 




• PANIC Button 


Dialog Box • 




• denne OiaJogHeioht 100 
•define DialogWidth HO 




I teraTemplate 


TextRecoro ■ 1 
2. 

5. 5, 15. J0<>, 
1 temDisable»statText. 
■\plt s time to- -.' , 
0. 0. NULL 




BttnColors ColorTable ■ < 
0x0050, 
0x00(0. 

0x0070. 

0x00 fo, 

0x0070 
1: 




ItemTemplate 


ButtonRecord - { 




)-. 


25. 5. 95. 105, 
out ton Item, 
\pPanic'. 
0. 0. iCol orTable 




DialogTenpiate 


DialogRecord - ( 

CIQ0 - DialogHeightJ / 2. 

(320 - DlalogWIdth) / 2. 

<190 - Dl a 1 ogtie 1 ght ) / 2 ♦ DialogHeight. 

C320 - DlalogVldthJ / 2 ♦ DlilogVldth, 

TRUE, 

NULL, 

VTextRecord. 

&ButtonRecord. 

NULL 




Panic" 






u'ratPortPtr DialogPtr; 
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DialogPtr = GetNevNodalDialog<&DialogRecord>: ErrChfcO; 
while (BodalDlalog<MJLL> !- |)[ /. Wall lor PANIC Button »/ 

CtoseDjalogCDialogPtr); ,, ^^ cJoM , the d|a|og #/ 



Program 11-3. Panic Button in Pascal 

, . m 

* PANIC Button Dialog Box « 

» 4 j 

PROCEDURE Panic: 



CONST 



DialogHeigM 
DialOgWIdth 

TextRecord: 

ButtonRecord: 

ButtonCelors: 

DialogRecora; 
DlalogPort i^ 
TextString: 
ButtonStnng: 



- 100: 

- 110; 

ItemTemplate; 
I temTempIate: 
ControlColorTbl 

DlalogTemplate; 
DialogPtr; 
String; 
String; 



BEGIN 



TextString :- 'It's time to...' 
ButtonStnng. :■ 'Panic : 

WITH TextRecord DO BEGIN 



ItenlD 


■■• 2: 


SetRect 


(Itemftect. S. 5. 15. IDS): 


ItWTypa 


•■• ItemDIsable+StatTextltera 


ItemDescr 


:■ STextStrifiB; 


ItemValue 


i- 0: 


ItMiPlag 


i- 0; 


ltemColor 


:- nil; 


END; 




WITH ButtonColors DO BEGIN 


SumpOut I me 


:- »00SO: 


SlmpNorBack 


:- »00f0; 


SimpSelBack 


:= W070; 


SlmpNorText 


:a aOOfO; 


SimpSelText 


:» »OO70s 


END: 




VI TH ButtonReeord DO BEGIN 


I teen] D 


:» 1| 


SetRect 


CHemRect, 5, 25, 105. *»S>; 


ItentType 


•■ Button] tern: 


I temDescr 


:- BButtonStrlng; 


ItetnValue 


s- 0: 


ItemFlag 


«■ 0) 


Itancoior 


:= BButtonColora; 


END; 




WITH DialogRecora DO BEGIN 


SetReetCboun 


dsRect, 
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(320 - DlalogVidth> / 2. 

(190 - DlalogKetght) / 2, 

«32Q - DialogWidth) / 2 + DialogWidth. 

(190 - DialogHetght) / 2 ♦ DlalogHeight >i 



divisible 


.-* TRUE; 


ot Ret Con 


=* o; 


IteolPtr 


■■ QTextRecord; 


Item2Ptr 


-.» g But ton Record: 


Terminator 


:- nils 



END: 

DialogPort r- GetNevfloaalDlalWDjalogBecord) i ErrChk: 

REPEAT UNTIL NodalDialogtni I > * l: < Wait tor PANIC button ; 

ei6»DI*laatDiilaBPaFt)i ( Then eloge th? mm I 



Changing Values 

This section describes how a control can be manipulated after it 
has been defined. Some of the functions to manipulate a control 
are listed under the Dialog Manager; the ones listed below are un- 
der the Control Manager. 

The Control Manager must have a handle to a control before 
that control can be manipulated (unlike the Dialog Manager, which 
requires only an ItemlD). To get a control's handle, a call is made 
to the Dialog Manager's GetControlDItem function. Once the han- 
dle is obtained, the various Control Manager routines that manipu- 
late a control can be used. 

Controls can be highlighted or inactive (dimmed), visible or in- 
visible, and selected or unselected. Make sure you know and un- 
derstand these differences. 

When a control is dimmed, it appears fuzzy in the dialog box. 
Clicking the mouse on the control will not activate it, just as select- 
ing a dimmed menu item won't work. 

A visible control is one you can see. A control can be made in- 
visible, for example, when an option is not available, or as was 
demonstrated in Chapter 10, to page text. 

Another attribute of a control is to be selected or unselected. 
This normally affects only two controls; the check box and radio 
button. When either of those buttons is selected, its button or box 
is filled, meaning whatever function it represents is active. (See the 
COLOR example from Chapter 10 for a demonstration.) 

The following sections illustrate how the Control Manager can 
be used to dim, hide, or activate a control. 
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Dimming controls. The following routines will dim or high- 
light a control using the HiliteControl function in the Control 
Manager. 

HiliteControl can specify whether a control is to be redrawn as 
normal or inactive, or whether a specific part code of the control 
can be individually highlighted. (The entire control is always re- 
drawn each time HiliteControl is called.) 

The parameter determining how the control is highlighted is 
referred to as HiliteState. It's a word-sized value, though only the 
least significant byte holds any meaning: 
HiliteState Value Highlighting 

Control is highlighted 

Only specified parts are highlighted 

Reserved (not used) 

Control is dimmed 

Part codes are used to identify the individual parts of a control. 
In the normal operation of a DeskTop application, your program 
will probably never need to manipulate any individual part codes. 
(You'll either be dimming or highlighting the entire control.) 

But, for the curious, Table 11-13 shows the part numbers de- 
fined for specific controls. Values 32-127 are available for your 
application's use. Any other value not listed is reserved. 

Table 11-13. Controls' Part Numbers 



1-253 

254 

255 





Code 




Decimal 


Hexadecimal 


Part 





$00 


None 


2 


$02 


Simple button 


3 


$03 


Check box 


4 


$04 


Radio button 


5 


$05 


Up arrow 


6 


$06 


Down arrow 


7 


$07 


Page up 


8 


$08 


Page down 


9 


$09 


Static text 


10 


$0A 


Grow box 


11 


SOB 


Edit line 


12 


$0C 


User item 


13 


Si'I) 


Lqfi§ static test 


14 


$0E 


Icon 


129 


$81 


Thumb 
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The following code can be used to dim a control. 
In machine language: 



pushlong 


*0 


•Jong reeu.lt apace 


pusnlong 


DlalogPtr 


;dlalog box port pointer 


pushword 


ItemID 


;the control' a ItemID 


_QetControlDItem 




;Dlalog Manager Call 


pulllong 


ControlHandle 


.return a handle to the control 


pea 


2B5 


;dlm the control 


puehJong 


ControlHandle 




_HltlteContro!i 







In C and Pascal: 

HtllteControl(2B5, GetControlDItem(DlalogPtr, ItemID)); 

Conversely, the following code will highlight a dimmed con- 
trol (or simply redraw a highlighted control). 
In machine language: 

;long result apace 

;dlalog box port pointer 
;the control's ItemID 



.redraw the control normal 



In C and Pascal: 
Hill teContro 1(0,. GetContwlDItem(DlalogPtr, ItemID)): 

Control visibility. The easiest way to make a control visible 
or invisible is by setting or resetting bit 7 of its ItemFlag. If bit 7 is 
reset to 0, the control is visible. If bit 7 is set to 1, the control is 
invisible. 

The Dialog Manager functions HideDItem and ShowDItem can 
be used to alter the visibility of a control after it's been defined, 

In machine language: 



pusblong 
pushing 
pushword 
_OetControlDItem 


•0 

DlalogPtr 

ItemID 


pulllong 


ControlHandle 


pea 

ushlong 




ControlHandle 

_HllltaControl 



pusnlong 


DlalogPtr 


;dlalog box pointer 


pushword 


ItemID 


;ItemID of the control 


-HideDItem 




Tender It Invisible 


jsr 


ErrChk 


:test for error UB0C (item not found) 
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In C and Pascal: 
HldeDItem(DlalogPtr. ItemID); 

To make a control visible, simply replace the above HideDItem 
functions with ShowDItem. Note that showing an item already vis- 
ible, as well as hiding an item already hidden, has no effect. 

To hide a control using the Control Manager, some extra steps 
are required. Actually, it's recommended you use the above Dialog 
Manager functions. However, if you're partial to the Control Man- 
ager, you'll need to call GetControlDItem (in the Dialog Manager) 
to return the control's handle, then perform either the Control 
Manager's HideControl or ShowControl function. 

In machine language; 



pusblong 


"0 


;](mg result spaoe 


push long 


DlalogPtr 


;dlalog boi port pointer 


push word 


ItemID 


;the control's ItemID 


—GetControlDItem 




;keep the control handle on the 


—HideControl 




;Hlde it 



In C and Pascal: 

HideControl(GetControlDItem(DlalogPtr, ItemID)); 

To show the control again, replace the HideControl functions 
above with ShowControl. 

Chapter Summary 

The following tool set functions were referenced in this chapter. 

Function: $0210 
Name: CtlStartUp 

Starts the Control Manager 
Push: UsertD (W); Direct Page (W) 
Pull: Nothing 
Errors: $1001 

Function; $0310 

Name: CtlShutDown 

Shuts down the Control Manager 
Push; Nothing 
Pull: Nothing 
Errors: None 
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Function: $0910 

Name: NewControl 

Creates a control 
Push: Result Space (L); Window Pointer (L); Control's Rectangle 
(L); Title String (L); Item Flag (W); Initial Value (W); Extra 
Parameter 1 (W); Extra Parameter 2 (W); Definition Procedure 
(L), RefCon (L); Color Table (L) 
Pull: Control Handle (L) 
Errors: None 

Function: S0E10 

Name: HideControl 

Hides a control, making it invisible 
Push: Control Handle (L) 
Pull: Nothing 
Errors: None 

Function: $OF10 

Name: ShowControl 

Shows a control, making it visible 
Push: Control Handle (L) 
Pull: Nothing 
Errors: None 

Function: $1110 

Name: HiliteControl 

Highlights or dims all or part of a control 
Push: HifiteState (W); Control Handle (L) 
Pull: Nothing 
Errors: None 

Dialog Manager Calls 
Function: S0D15 
Name: NewDItem 

Places a control into a dialog box 
Push: Dialog Pointer (L); ItemID (W); Rectangle pointer (L); 

ItemType (W); Item Descriptor (L); ItemValue (W); Item Flag 
(W); Color Table Pointer (L) 
Pull: Nothing 
Errors: $150A, S150B 

Function: S1E15 

Name: GetControlDItem 

Returns a control handle for a dialog box item 
Push: Result Space (L); Dialog Pointer (L); ItemID (W) 
Pull: Control Handle (L) 
Errors: S150C 
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Function: $2215 
Name: HideDItem 

Hides a control in a dialog box, rendering it invisible 
Push: Dialog Pointer (L); ItemID (W) 
Pull: Nothing 
Errors: S150C 

Function: $2315 

Name: ShowDItem 

Makes an item or control in a dialog box visible 
Push: Dialog Pointer (L); ItemID (W) 
Pull: Nothing 
Errors: $150C 

Function: $2F15 

Name: 5 etDl tern Value 

Changes the value of an item, or selects an item 
Push: New Item Value (W); Dialog Pointer (L); ItemID (W) 

Pull: Nothing 
Errors: $150C 

Function: $3215 

Name: GetNewModal Dialog 

Creates a modal dialog using a template 
Push: Result Space (L); Template (L) 
Pull: Dialog Pointer (L) 
Errors: Possible Memory Manager errors 
Function: $3315 

Name: GetNewDItem 

Places an item or control into a dialog box using a template 
Push: Dialog Pointer (L); Template (L) 
Pull: Nothing 
Errors: $150A, $150B 

Memory Manager Calls 
Function: $0902 
Name: New-Handle 

Makes a block of memory available to your program 
Push: Result Space (L); Block Size (L); UserlD (W); Attributes (W); 

Address of Block (L) 
Pull: Block's Handle (L) 
Errors: $0201, $0204, $0207 
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Interrupts 

Interrupts. The very word 
evokes trepidation in even the 
most experienced programmer. 
Now, before you flee to the 
next chapter in terror, you'll 
find that interrupts on the IlGS 
are not only an essential part of 
the computer, but they're also 
a lot of fun. 

The first section of this 
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chapter cushions the introduction to interrupts for the programmer 
who hasn't experienced an ordeal with them yet. It also presents 
the various forms of interrupts and task-switching capabilities that 
come as standard equipment on the Apple IIGS. 

A collection of sample programs are used as the basis of study 
throughout the chapter, and you ought to find them exceptionally 
interesting, or at the very least, entertaining. 



Since interrupts involve working at the hardware level of the 
computer, you have to work with them in machine language. 
This doesn't mean that you cannot work with interrupts from 
C or Pascal. You can. But in order to understand the workings 
of interrupts, a knowledge of machine language is required. If 
you're a C or Pascal fan, you can take the ideas and low-level 
routines from the example programs in this chapter and link 
them with your own programs. 



This chapter will concentrate on exploring the Toolbox's role 
iii working with interrupts. 

What Are Interrupts? 

An interrupt is a signal that causes the microprocessor to stop its 
work and momentarily switch to something else. That "something 
else" is called an interrupt handler, also known as an interrupt ser- 
vice routine. An interrupt handler takes only a split second of pro- 
cessor time to complete its work, and then the microprocessor 
returns to its previous task. 

A familiar interrupt on the IlGS is the invocation of the control 
panel. Pressing Control-Open Apple-Escape freezes the current 
program and brings up a new one: the Classic Desk Accessory 
menu. When finished with the control panel, the program that was 
interrupted continues where it left off, as though nothing had ever 
happened. The keyboard is one part of the computer that can gen- 
erate an interrupt. 

In computers such as the Apple IlGS, in which many things 
seem to happen all at once, the ability to share slices of processor 
time among routines is what keeps things running smoothly, It also 
frees the programmer from having to watch for certain events at 
every turn of the program. Imagine what a pain in the flowchart it 
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would be if you had to keep an eye on the mouse location, move 
the pointer around, update the screen underneath, and so on. Since 
the mouse can generate interrupts when it is moved, or when its 
button is pressed, mouse interrupt handlers take care of all the 
mouse-related business behind the scenes. 

Another source of interrupts is the serial port. These interrupts 
come into play when you have a modem connected to the com- 
puter white data is racing through the phone line. Each time a 
character comes through the modem and into the computer's mo- 
dem port, an interrupt signal is generated. This causes a serial port 
interrupt handler to investigate all the commotion. When the han- 
dler discovers a character waiting at the port, it snatches the char- 
acter away into a buffer, where it will be processed when the 
modem program is ready for it. This ensures that no characters will 
be lost if the computer is busy working on some other task. 

Interrupts play a very important role in the operation of the 
Apple IlGS, especially since they are far more significant to the 
workings of that computer than they have been to any of its prede- 
cessors. But the correct handling of interrupts is one of the most 
tenuous programming tasks the budding IlGS programmer will face. 
Fortunately, the Apple IlGS has a few Toolbox functions that make 
working with interrupts easier and safer. 



Safer? Well, let's just say that if your custom interrupt handler 
is incorrectly written, you might find that it does a great job of 
reformatting your hard disk, even if you weren't writing a disk 
utility. 

Careful, precise handling of interrupts is imperative. So 
pay strict attention to the rest of this chapter if you haven't 
been scared away yet. 



Types of Apple IlGS Interrupts 

In the previous section, three main sources of interrupts on the Ap- 
ple IlGS were introduced: the keyboard, the mouse, and the serial 
port. These are considered external hardware interrupt sources 
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since they're activated by influences outside of the computer. 

The Apple IlGS has many internal interrupts as well mostly 
related to circuitry in the machine. The following is a list of some 
of the interrupts that can occur in an Apple IlGS: 

Type Example Interrupt Activity 

Reset Turning on the computer 

Reset Control-Reset, Control-Open Apple-Reset, or Diagnoses 

Abort Memory fault error (from expansion RAM) 

IRQ Any keypress executed while the Event Manager is active 

]RQ Keyboard flush (Control-Open Apple-Delete) 

IRQ Desk Accessory menu (Control-Open Apple-Escape) 

IRQ Mouse movement or button press 

IRQ Serial port (register state changes, and so on) 

IRQ Firmware print spooling (buffer refresh) 

IRQ Video graphics controller (scan line, VBL, and so on) 

IRQ Ensoniq DOC (sound RAM refresh signal) 

IRQ Realtime clock (one second, quarter-second) 

Software BRK instruction encountered 

Software COP instruction encountered 

Interrupts come in five basic flavors: 

Interrupt Explanation 

IRQ Maskable interrupt request 

NMI Nonmaskable interrupt 

Software Software interrupt (BRK or COP) 
Reset System reset interrupt 

Abort Memory access abort interrupt 

Maskable Interrupt request (IRQ). A maskable IRQ interrupt 
is generated by a peripheral card or some other type of hardware 
that is physically or logically connected to the computer. A mouse, 
keyboard, serial port, Ensoniq DOC clock, video graphics control- 
ler (VGC), and other such interrupt source generates IRQ inter- 
rupts. These can be masked (ignored) by the processor if the 
interrupt disable bit in the processors status register is set (win the 
SE1 instruction). Using the CLI instruction clears the disable bit, 
which means the processor will resume handling interrupt requests, 
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Just for kicks, enter the following BASIC program into 
Applesoft BASIC and run it. 

10 SB! = 120 : CLI ~ 86 : FITS - 96 

20 POKE 788, SKI 
30 POKE 769, HTS 
40 CALL 768 

Now, try to bring up the Classic Desk Accessory (CDA) 
menu by pressing Control-Open Apple-Escape, You'll find 
that it refuses to pop up. This is because the 65816 processor 
is set to mask the interrupts that the ADB (Apple DeskTop 
Bus) Keyboard Micro is sending whenever the CDA menu is 
requested. 

Change the SE1 in Line 20 to CLI and rerun the program. 

As soon as you press the Return key after typing RUN, 
the CDA menu appears. This will be discussed in detail later 
in the chapter. 



Nonmaskable interrupts. Although no built-in source exists, a 
nonmaskable interrupt (NMI) is supported by the Apple IlGS. A 
nonmaskable interrupt is just like an IRQ except that (as you might 
guess) the processor cannot mask it out. Some Apple It peripherals, 
Mich as a screen snapshot-to-printer card or a hardware diagnostic 
card, can generate NMIs, 

Software interrupts. A software interrupt can be generated by 
executing a BRK or COP machine language instruction. In one 
sense, these are nonmaskable interrupts; even if the processor's in- 
terrupt disable flag is set (SEI), a BRK instruction is still performed. 
BRK is used mainly for debugging purposes to insert a programma- 
ble break point in your programs, COP is intended to kick a 
coprocessor card — a math coprocessor, for example — into action. 

Reset interrupts. Reset interrupts are generated mainly by 
pressing Control-Reset, Control-Open Apple-Reset (reboot), or 
Control- Open Apple-Option-Reset (diagnostics), or by turning on 
the computer. A reset interrupt can be simulated through software 
by sending a command to the Apple DeskTop Bus, or by directly 
calling the reset handler code in ROM ($00FA62 in emulation 
mode). 



275 






. Chapter 12 

Abort interrupts. The Apple IlGS currently does not make use 
of an abort interrupt even though it is supported. Aborts are gener- 
ated when access is made to an off-limits portion of memory, 
something all multi-user computers employ to keep users from 
poking around in other people's memory space. Should the IlGS 
become a true multi-user computer, this police-style interrupt 
would be valuable for maintaining security. 

When an Interrupt Occurs 

Here's a brief rundown of what happens when the processor is in- 
terrupted (that is, as long as interrupts aren't being masked). Keep 
in mind that all of this happens within a few milliseconds: 

• When the computer is interrupted, a program in the Apple IlGS 
ROM, the firmware interrupt manager, runs through a checklist of 
tasks to service the interrupt. It first determines which set of inter- 
rupt vectors should be used, depending on emulation mode. 
(These vectors are listed in Appendix B of Mastering the Apple lies 
Toolbox, available from COMPUTE! Books.) 

• The processor speed kicks in to fast mode. 

• The type of interrupt is then determined. If it's due to a BRK or 
COP instruction, one of the software interrupt handlers is called. 
If the handler is not installed, the user is sent directly to the Ap- 
ple IlGS monitor. 

. Machine-state information (that is, registers and flags) is saved at 
this point, before the serial port is tested to see whether it origi- 
nated the interrupt. If it did, either AppleTalk or a serial port inter- 
rupt handler is called. 

• Finally, if the interrupt wasn't due to a software instruction or ac- 
tivity at the serial port, the rest of the machine-state information 
is saved, and then all the other internal interrupt sources (the 
clock, the VGC the mouse, and so on) in the computer are in- 
terrogated. If an internal source generated the interrupt, the inter- 
rupt manager calls the appropriate handler. 

■ If the interrupt wasn't from an internal source, but was from a pe- 
ripheral card in one of the slots, the computer slows down to the 
old Apple II speed of 1 MHz, and jumps to the user interrupt vec- 
tor at location $3FE in Bank $00. When ProDOS first runs, it sets 
this vector to point to its own internal interrupt manager. The 
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manager is responsible for finding some way to service the inter- 
rupt. This means that every handler associated with a peripheral 
card should determine whether its card generated the interrupt. 
The duties of such a handler are discussed later in the chapter. 

• Once a handler claims the interrupt and services it, the processor 
restores the machine state and continues execution from the point 
where it was interrupted. 

■ However, if the interrupt is not claimed (and, as a consequence, 
not serviced), a fatal error occurs. If ProDOS is unable to have the 
interrupt serviced, it calls a fatal error handler. (In ProDOS 8 this 
handler would set the screen to 40 columns and display INSERT 
SYSTEM DISK AND RESTART— ERR 01). The user interrupt vector 
is used mainly by eight-bit data communications programs in ser- 
vicing interrupts from internal modems or communications cards. 

Writing a Handler (Using Blanks) 

The Toolbox provides a host of useful functions that make working 
with interrupts a snap. This section of the chapter will ease you 
into writing an interrupt handler. The first program example 
doesn't use interrupts, but it simulates the process of the steps re- 
quired for real-life interrupt handling. 

Actually, this example is quite useful (and fun). The program 
patches the Apple IlGS's system bell vector with a new beep. After 
installing this program, the computer will beep with a fweep sound 
reminiscent of a screaming banshee. No more dull, boring bonk 
sound. 

The following is the plan of attack for creating the beep. 

Setup program. First, start up just the three tool sets: Tool Lo- 
cator, Miscellaneous Tools, and Memory Manager. 



Main 



ABSADDR 


ON 




KEEP 


BeepSstup 




mcopy 


BeepMacpofl 


(use MACGEN to create « 


START 






pbk 






plb 




data bank = code bank 


_TLStartUp 




start Tool Locator 


-MTStarttJp 




start Mlso Toole 


pha 




result space 


_MM Startup 




start Memory Manager 


pla 




pull User ID 


ata 


UserlD 
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Next, call GetNewID to create a new User ID which will be 
used in allocating a new handle for the beep routine. 



pha 

PUSHWOHD 

_GetNewID 


•IA00Q 


result space 
;Type ID / Aux ID 
;make an ID 


pla 
eta 


CodelD 





Then ask NewHandle to allocate a small portion of RAM with 
the attributes of $C018: It can be any bank or any address, does 
not need to be page-aligned, and cannot use special memory, cross 
a bank boundary, or be purged or moved at all. 
pna ;result space 



;Slze of block 
;CodeID for this handle 
:Flxed. looked, bolted down 
:addresa of the block 



pba 




PU8HL0KG 


*MBEnd-MyBeep + l 


PUSHWOHD 


CodelD 


PUSHWOHD 


•icoie 


PUSHLONG 


*o 


_NewHandle 




pla 




pix 




eta 





otx 


z 


Ida 


[0] 


ata 


BlkAddr 


ldy 


*z 


Ida 


[0].y 


sta 


BlkAddr + 2 



;get handle 



;get long address of block 



Once the handle is created and its address determined, place 
the beep code there by using the BlockMove function. (Yes, the 
beep routine has to be written as relocatable code. Don't fret. The 
65816 has some helpful instructions that make it possible to write 
relocatable code.) 



PUSHLONG 


*MyBeep 


.Source 


PUSHLONG 


BlkAddr 


.Destination 


PUSHLONG 


*MBEnd-MyBeep+l 


.Size 


_BlockMove 







Finally, SetVector is used to patch the beep vector to point to 
the new beep routine. This program shuts down, and you've 
finished. 
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jiiiei i ujjia 




PUSHWOHD 


**001B ;Bell Vector Heference 




PUSHLONG 


BlkAddr ;New Beep Vector Address 




-SetVector 






PUSHWORD 


UserlD shutdown everything 




_MMShutDown 






—MTShutDown 






-TLShutDown 






rtl 






UeerlD 


de 




a 


Code ID 


ds 




2 


BllAddr 


ds 




4 


The code that follows is the actual beep routine that is relo- 


cated into safe 


memory 


Every time the HGS is called to beep the 


speaker 


this small routine is called. 


Speaker 


equ 


IS0C030 speaker toggle location 


My Beep 


longa 


off 






long] 


off 






pha 




ipreaerve the registers we munge 




phy 








phx 






FweepO 


ldx 


'32 




Fweepl 


ldy 


*4 




FweepU 


Ida 


Speaker 




txa 








sec 






Waltl 


pha 






Walt£ 


Bbo 


•1 






bne 


Walt2 






pla 








boo 


'1 






bne 


Waltl 






dey 








bne 


Fweep3 






dex 








bne 


Pweepl 






pli 




xestore registers 




ply 








pla 








clc 




ireturn with carry clear 


MBBnd 


rtl 

END 
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Assemble this with APW and run the resulting EXE file to in- 
stall the new beep. (If you're hunting for a way to get the machine 
to beep at you so you can hear it, pull up the CDA menu and press 
the space bar or any other illegal key). As long as the computer is 
turned on, this new beep will be used in place of the old sound. 



Imagine the fun you could have with this if a digitized sound 
sample were played through the Ensoniq chip, rather than the 
all -too-common beep. 

If you end up liking this new beep better than the bonk 
sound the IIGS normally makes, you can make the process of 
patching the bell vector part of your ProDOS 16 boot se- 
quence. Just change the file type of the EXE file to TSF ($B7) 
and copy it to your system disk's SYSTEM/SYSTEM.SETUP 
directory. It is a TSF (Temporary Startup File), because the en- 
tire program doesn't need to be kept in memory. Only the 
beep portion has to be retained. Every time you boot into 
ProDOS 16, this new sound will replace the old one, even 
when you're running ProDOS 8 programs. 

Should you wish to go back to using the standard IlGS 
bell sound, just move the new beep program out of the 
SYSTEM.SETUP directory and reboot. 



This program is an excellent model for getting started on an 
interrupt installation and servicing program. Some important points 
need to be made about this program and how it relates to interrupt 
handlers: 

• First, before writing any interrupt handler, consider the program- 
ming environment. In the case of this new beep routine, the beep 
code must be accessible at all times and the code must not be 
overwritten, That's why a special patch of RAM is allocated by 
NewHandle explicitly for the beep routine. Since emulation mode 
programs use banks $00, SOI, SEO, and $E1 of the computer, the 
beep routine could not reside there. The beep code had to be 
placed outside of special memory, (See Chapter 7, which deals 
with memory management, foT more details). 
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* The entire installation program is needed only once to install the 
beep into safe memory and set up the new bell vector. That's why 
NewHandle is called to allocate space only for the beep handler 
code, Why waste memory? 

* Since NewHandle could end up placing the code anywhere in the 
machine, the code had to be written so that it didn't use any self- 
referencing addressing modes. Of course, in this example, that's 
not a problem. For larger applications, such a program would 
most likely become a relocatable load segment (more on this and 
other disk-related matters in Chapter 14), 

* The beep routine properly maintains the environment by saving 
registers before changing them, and then restores them before re- 
turning. The handler should avoid modifying any other environ- 
ment settings (displaying a message on the screen, changing video 
modes, and so on). 

According to the rules, the Apple IIgs's system bell routine is 
always called in emulation mode with eight-bit registers and must 
return with the carry clear via an RTL instruction. As with an inter- 
rupt handler, there are certain steps to follow to ensure that every- 
thing is done correctly, 



Recall the sample Applesoft program from the previous sec- 
tion. When run, it caused the computer to ignore interrupts so 
you couldn't go into the CDA menu after pressing Control- 
Open Apple-Escape. As soon as interrupt recognition was 
turned on with the CLI instruction, the CDA menu popped up 
instantly, without your having to press Control-Open 
Apple-Escape again. Strange? Not at all. 

The reason this happened is because the interrupt of the 
Keyboard Micro, part of the Apple DeskTop Bus, was still 
pending and required servicing. The interrupt request line on 
the CPU was like a telephone that kept ringing until it was fi- 
nally answered by the 65816 microprocessor. Once interrupt 
recognition was reestablished, the processor discovered the in- 
terrupt was pending and went out to find a way to service it. 
That's why the CDA menu seemed to come up all on its own. 
You might chalk it up to delayed reflexes. 
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Interrupt 


Vectors 


The Beep.Setup program in the last section introduces the Miscella- 


neous tool set's SetVector function: 


Function: 


$1003 


Name; 


SetVector 




Installs an interrupt vector address 


Push: 


Vector reference number (W); Address of routine (L) 


Pull: 


Nothing 


Errors: 


None 


Comments: 


This installs the vector address, but not the interrupt service 




routine itself. 


SetVector is used to change a multitude of system vectors and 


interrupt handler vectors. The vectors are identified by a unique ID 


number, as shown in this table: 


Reference ID Vector Description 


$0000 


Tool locator (primary) 


$0001 


Tool locator (secondary) 


$0002 


User's tool locator (primary) 


$0003 


User's tool locator (secondary) 


$0004 


Interrupt manager 


$0005 


Coprocessor (COP) manager 


$0006 


Abort manager 


$0007 


System death manager 


$0008 


AppleTalk interrupt handler 


$0009 


Serial communications controller interrupt handler 


$0O0A 


Scan line interrupt handler 


$000 B 


Sound interrupt handler 


$OO0C 


Vertical blanking interrupt handler 


S000D 


Mouse interrupt handler 


$000E 


Quarter-second interrupt handler 


$000F 


Keyboard interrupt handler 


$0010 


ADB-response-byte interrupt handler 


$0011 


ADB-SRQ interrupt handier 


$0012 


Desk accessory manager (Control-Open Apple-Escape) 


$0013 


Keyboard -flush -buffer handler (Open Apple-Delete) 


$0014 


Keyboard -micro interrupt handler 


$0015 


One-second interrupt handler 


$0016 


External- VGC interrupt handler 


$0017 


Other unspecified interrupt handler 


$0018 


Cursor-update handler 


$0019 


Increment-busy-flag routine 


$001A 


Decrement-busy-flag routine 


282 





$001B 


Bell vector 


$001C 


BRK vector 


$001D 


Trace vector 


$001E 


Step vector 


$001F-$0027 


Reserved 


$0028 


Control-Y vector 


$0029 


Reserved 


$002A 


ProDOS 16-ML1 vector 


$002B 


Operating system vector 


$002C 


Message- pointer vector 



The actual locations in memory where the vector addresses are 
stored are presented in Appendix B of Mastering the Apple UGS 
Toolbox. 

SetVector's function is to install the address of a new system or 
interrupt handler. This is superior to the old global page scheme, 
where any program had access to all of the system's vectors and 
could destroy them accidentally. Also, using a tool to set vector ad- 
dresses means that changes in vector storage locations in later 
ROM revisions will never be a problem. 

SetVector's partner is GetVector. GetVector is used to retrieve 
the long address of a system/interrupt handler. 

Function: $1103 
Name: GetVector 

Returns the address of an interrupt vector 
Push: Result Space (L); vector reference number (W) 
Pull: Vector's address (L) 
Errors: None 

Patching out a vector that will be used only momentarily re- 
quires the use of both of those Miscellaneous tool set functions. For 
example, the following routine demonstrates how you get the cur- 
rent vector address for the monitor's Control-Y vector, patch it out, 
and then restore it: 



Setlt 



pushlonj 


*0 


push word 


•*0028 


—GetVector 




pull long 


OWCtrlY 


push word 


**0028 


pushlong 


•NewVect 


_SatVector 




rta 





;puah long result apace 
;Vector ID = Control-Y vector 
retrieve the current address 
;save it for later 
;Veetor ID = Control-Y vector 
:new Control-Y handler address 
;eet It 
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• Your program then does whatever It must do with the new 

• Control-Y vector installed. Before your program quits. 
' It restores the old vector address like so. . . 

UnSatlt pushword *I0028 

pushlocg OldCtrlY 

-SetVector 
rte 



OldCtrlY do 



;long storage for old Ctrl-Y address 



GetVector and SetVector can also be used to hook into an ex- 
isting handler without actually replacing it. For example, if you 
wanted to have the keyboard flush handler play a digitized sound 
sample of a toilet flushing, but still flush the keyboard's type-ahead 
buffer, you'd proceed as follows: 

• Installation 

• Get the keyboard-flush handler address with GetVector. 

• Set the keyboard-flush handler vector with your own routine's 
address using SetVector. 

• Handler operation 

• When the user presses Open Apple-Delete to flush the keyboard 
buffer, your handler first plays your sound sample. 

• Then it jumps to the original keyboard-flush handler address 
(the address obtained by the GetVector call in the installation of 
your handler). 

Interrupts in ProDOS 16 

SetVector is one way to install an interrupt handler. You can also 
set one up by going through the operating system, ProDOS 16, if 
you prefer. This is done mainly for handlers that service interrupts 
from hardware installed in one of the seven peripheral slots in the 
IIGS. 

Normally, patching into the firmware vectors with SetVector is 
desired because less overhead is involved since the operating sys- 
tem is bypassed, But the firmware vectors only support those inter- 
rupts indigenous to the circuitry in the lies and do not make 
provisions for interrupts from peripheral cards. For these, you have 
to go through ProDOS 16. 
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To install an interrupt with ProDOS 16, your program would 
use the ALLOC-1NTERRUPT ProDOS 16 function (number 
$0031): 



_^LLOC_INTERRUPT IParms 
bos Error 



■.Allocate the Interrupt 
;branch If error 



To remove the interrupt allocation in ProDOS, the 
DEALLOC_INTERRUPT function is used (number 



-DEALLOC-INTEBRUPT 
DCS 



IParms 
Error 



The parameter table for these calls consists of a word and a 
long word: 



IParms 

lnt__num 

lnt_code 

Offset 

+ $00 
- 502 



anop 

ds 

do 

Size 

word 
long 



14TheHandler' 



.tills value le returned by ProDOS 
;the address of the handler 



Description 

int_num: Interrupt handler number 
int_code: Address of interrupt handler routine 



Actually, only the first parameter is required for 
DEALLOC—1NTERRUPT, but in practice the same parameter 
block is usually referenced. 



When ALEOCJNTERRUPT is used, ProDOS 16 will assign 
your interrupt handler a unique number which is returned in the 
first word, int_num. Each time you reference your handler through 
ProDOS, you use this number (as in the case of memory blocks 
with the Memory Manager). 

Possible error codes returned by these calls are 

Error 

Code Meaning 

$07 ProDOS is busy (it's in the middle of a command already) 

$25 Interrupt vector table full (there are already 16 allocated) 

$53 Invalid parameter (the handler's address is beyond SFFFFFF) 

If ProDOS is busy, you'll have to let it finish what it's doing 
and then try to allocate the interrupt again later. This is an unlikely 
event, unless you try to allocate another interrupt and you're al- 
ready inside an interrupt handler. 
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Once your interrupt is allocated with ProDOS 16, you can turn 
on the source of the interrupt and begin handling it. When you 
wish to deallocate your interrupt, first turn off the interrupt source; 
then deallocate it. 

Environment 

When an interrupt handler is called, the computer is placed into a 
known state, depending on the type of interrupt your handler ser- 
vices and how it is registered with the system. For example, an in- 
terrupt handler set up via SetVector can expect the following 
standard machine configuration: 

Code Bank = The bank containing your handler 

Data Bank = $00 

Emulation = Off (Native mode) 

Registers = Eight-bit widths, contents undefined, carry set 

Speed = Fast 

Your handler returns to the system interrupt manager via RTL. 

If your handler is called from the user interrupt vector at 
$00/03FE, you get the same results as indicated above, except the 
computer will be running at 1 MHz and emulation mode will be 
on. Your handler returns to the system interrupt manager via RTS. 

If the handler is installed through ProDOS 16, the standard 
configuration applies, but register widths are set to 16 bits. Your 
handler returns to ProDOS 16 via RTL. 

If your handler modifies any registers or other environmental 
aspects, it must restore any changes before returning. For example, 
if you change register widths or their contents, you have to restore 
them as they were when the handler was initially called. In addi- 
tion, the carry flag should be cleared before returning if your han- 
dler serviced the interrupt. If the carry is set, it indicates to the 
system that the interrupt was not serviced. 

The typical flowchart of an interrupt handler goes something 
like this: 

• Save all the registers and other machine-state information modi- 
fied in this handler. 

• Set up the environment as needed in order to service the 
interrupt. 

• If the handler services an interrupt on a peripheral card, deter- 
mine whether that card has an interrupt that needs service. 

• If it doesn't, set the carry flag and return. Otherwise, service the 
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interrupt, then clear the interrupt source. (For example, if your 
handler services one-second clock interrupts, it must reset that in- 
terrupt signal before returning. More on this in a later section.) 
• Restore the state information saved at the beginning of the han- 
dler; then clear the carry flag and return. 

Failing to restore the machine state before returning can result 
in some spectacularly nasty (and possibly fatal) system crashes. 

Writing a Handler 

Before you can write an interrupt handler, you need to know how 
to turn on the source that generates interrupts. For peripheral cards 
in slots 1-7, you'll have to adjust the soft switches mapped to the 
card's slot. Directions for doing this, and other technical infor- 
mation about the peripheral card, should be found in its manual. 

For sources built into the IlGS, the IntSource Miscellaneous 
tool set function is used to enable or disable interrupts for a par- 
ticular source. Using it is far easier than messing with softswitches, 
and it keeps your hands clean, too. 

Function: $2303 
Name; IntSource 

Activates or Deactivates an interrupt source 
Push: Source reference number (W) (see below) 

Pull: Nothing 
Errors: None 

Reference Number 

$0000 
$0001 
$0002 
$0003 
$0004 
$0005 
$0006 
$0007 
$0008 
$0009 
$000A 
$000B 
$00OC 
$00OD 
$000E 
$000F 



Description 

Enable keyboard interrupts 
Disable keyboard interrupts 
Enable vertical blanking interrupts 
Disable vertical blanking interrupts 
Enable quarter-second interrupts 
Disable quarter-second interrupts 
Enable one-second interrupts 
Disable one-second interrupts 
Reserved 
Reserved 

Enable FDB data interrupts 
Disable FDB data interrupts 
Enable scan line interrupts 
Disable scan line interrupts 
Enable external VGC interrupts 
Disable external VGC interrupts 
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So, to turn on vertical blanking (VBL) interrupts, your program 



uses 

pushword »*O0Q2 .Enable VBL Interrupts 
_JntSource 

To turn VBL interrupts off, use 

pusaword '10003 iDieable VBL Interrupts 
_IntSource 

Notice that all the Enable ID numbers are even, and their Dis- 
able counterparts are odd. Creative use of equates in your program 
can make such code self-documenting — for example: 



Enable 


gequ 





Disable 


gaqu 


1 


VBL 


gequ 

pUBhwopd 'Enable + VBL 

_JntSouroe 

pusbword 'Disable + VBL 
—IntSource 


2 



Do not attempt to turn on an interrupt source until you've in- 
stalled the corresponding handler. Doing so is like starting 
your car while it's in first gear and the clutch is out. 



The following complete program listing (Program 12-1) is an 
actual interrupt installation and handler. Almost as useful as 
changing the speaker's beep, this program will cycle through all 16 
border colors around your screen, Using the one -second interrupt 
source on the IIGS, the border color will continue to change every 
second, for a little longer than a minute. It then turns off the one- 
second interrupts, restores the original interrupt vector, and does its 
best to clean up memory by unlocking its memory block for purging. 
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Program 12-1. Sccond.ASM 




■ SeconO.ASM • 




• One-Second Interrupt Demo • 




ABSADDR CH 




IEEP Second 




MCOPY SeecfiO.Mac :Cr«4te using MACGEN on this (He 




Nam STAPT 




phk 




plb ;data bank = code can'. 




.TLStartUp jstart Tool Locator 




JfTStariUp isUtl Njsc Tools 




pha ; result space 




JMStartllp I atari Memory Manager 




pla ipull User ID 




si a User ID 




pna : result space 




PUSHVQRD HFOOO ;Type ID t Aux ID 




JtetNevID intake an ID 




pla 




sta CoaelD 




pha . reau 1 t space 




Pha 




PUSHIONG iSecEna-OneSec (Size or Block 




pushword Codejp ; Coo* ID for this hanaie 




PUSHVORD MCI IB iLocked. Fixed. <purge>2) 
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■ L.napier jz 






PUSHLONG 10 


: address ot the Block 






JievHandle 








PU 


;gei handle 






plx 








■sta 








stx 2 








Ids [01 


:oet long address of Block 






st a BlkAoar 








lay 12 








id4 10), y 








sta BlkAoar«2 








PUSHLONG *0 


: result space 






PUSHWOftD 1*001 5 


;One Second interrupt vector ID 






_<3*tvector 








PULLLONG OldVeet 


iretneve oia vector address 






PUSHLONG lOneSec 


i Source 






PUSHLOHC- BIKAoar 


I Destination 






PUSHLONG »SecEnd-OneSec 


iSize 






_B IOC* Nov* 


insove handler code 






PUSHW0RD «»0015 


iOne Second interrupt reference ■ 






PUSHLONG BKAoar 


;Ne« One Second interrupt handler address 






_Setv*etor 








PUSHWORD 1*0006 


i Enable 1-sec interrupt Rei Nun 






_lntSouree 


;turn interrupts on 






PUSHVORD User ID 


; shutdown everything 






JMShutDovn 








JfTShutDnwn 








_n..ShuiDoun 








_OUIT QParms 
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User [ D ds 


2 




BiMoar as 


A 




QParms ac 


HO 


:Pr 


de 


1*0000' 




• Interrupt 


Handler Code 


• 



Interrupts 



sProDOS 16 Quit Code parameters 



Border 60U IE0C034 

Scanlnt EOU »EOC032 



neSec L0NGA 


■OFF 


L0MG1 


on 


phb 




pha 




phx 




phy 




phk 




plO 




rep 


1*30 


LONG* 


:■. 


LCWG1 


ON 


per 


DataSect 



:RTC/Boroer color register byte 

;SCanline t I -sec interrupt source 



:Thi3 is the handler's entry point 



;save what u* end up mungihg 



idata bank = code oanx 
;l6-Oit registers 



:push address ot data section to stack 

sep »»20 accumulator « S-bita 

LONG* OFF 

Ida Border jijrab border color 

and i*F0 isave upper mottle <BTC Outs) 

Idy iColor-DataSect :store to Color record in data section 

sta c I .S> . Y 

Ida Border 
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Lnapier \L 




inc 


A {increment il (color is lower hidoie> 




ana 


f*0F ;tru"cstt any wrapping to upper niOOle 




Ora 


U.SJ.Y ;0R with RTC Cits 




ill 


Border : update the Dorder 




rep 


1*20 {accumulator - 16-Bits 




LONGA 


OH 




Idy 


iCycle-OataSeet :get Cycle record 




laa 


(I,8>.Y 




dec 


A ; decrement it 




sea 


tl.SJ.Y lupdate counter 




one 


Exit Hf counter is not zero, exit 




• Once we' ve 


:ycled through the numoer of ooraer changes specified. 




• we turn otl 


one-second interrupts, restore the ola vector, and 




• unlock this memory Block to mane it purgeable when needed. 




PUSHVORD t*0007 iDlsatsle I -sec interrupts Ret Hum 




.IntSource :'"rn '** oil first 




PUSHVORD ••0015 iPus*> '-See vector Ret Hum 




Idy 


•OldVect-DataSecl+2 




104 


iHZ.Si.'f {push high-word of old vector 




phi 






oey 






dev 


;( index low-word 5 




Ida 


(142*2,8}. X :push low-word o« old vector 




Phi 






_SetVector {restore old l-sec interrupt vector 




Idy 


•CodelD-DataSect 




Ida 


tl.SJ.Y ipush code ID 




pna 






.HUnLockAII :un lock this Block 
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1 



Exit pla 



Sep M30 

LONGA OFF 

LONG I OFF 

laa 1*00100000 

sta Scanlnt 

piv 
Pla 



pla 

PID 

elc 
rtl 

DataSect 

Co I or ds 
Cvc | « de 
OldVect ds 
CooelD os 
SecEfd AN0P 



AN0P 
I 

I 6-1 

4 



Interrupts 



ipull PC relative value olt stack 



|8-Dlt registers 



iclear l-sec interrupt source 



^restore registers 



^interrupt serviced, return 



iTemporary color value workspace 
iNumoer of tines Doroer eolor changes 
iOrigmai l-sec interrupt handler address 
;US*r-ID 01 this memory segment 



Installation of the interrupt handler is similar in most respects 
to the Beep.Setup program listed earlier in this chapter. The only- 
things different are 

• The ID attributes for the GetNewID call do not reference a setup 
routine. 

• The New-Handle attributes assign the memory block a purge level 
of 2. Even though level 3 means most purgeable, it is reserved for 
use by the system loader. Since the block is locked, it can't be 
purged until it is unlocked. 

• The current vector for one-second interrupts is preserved before 
it's changed by the SetVector function. 

• IntSource is used to turn on one-second interrupts. 
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Of course, the handler itself is quite different. Here is a break- 
down, starting from the top and dissecting it through to the end, of 
what the handler does: 



OneSac 



LONGA 
LONGI 



OFF 
OFF 



;Thls Ib the handler's entry point 



Since this routine is called from the firmware interrupt man- 
ager, the system will be placed into native mode with eight-bit reg- 
isters. Thus, the assembler needs to be placed into the same state at 
the top of the routine by using the LONGA and LONGI directives. 

phb ;save what we end up destroying 

pha 

phx 

phy 

The data bank, accumulator, and X and Y registers are al! 
changed in this routine, so they must first be saved by pushing 
their values onto the stack. 



pnk 






plb 




;data bank = code bank 


rep 


*tm 


;16-btt registers 


LONGA 


ON 




LONGI 


ON 





Next, the data bank register is set to the code bank register 
since this routine runs and accesses data in the same bank. It 
switches in 16-bit registers and tells the assembler to do likewise. 

per DataSeot .push address of data section to stack 

This is a new instruction to most 65816 programmers. PER is 
used to push the program counter (plus an offset) onto the stack 
for use in accessing portions of a relocated program. By putting the 
16-bit runtime address of the program's data section on the stack, 
stack-relative indirect addressing can be used to access the data. 
This makes writing relocatable code nearly painless. 

Try doing this with the venerable 6502! 



sep 


**W 


accumulator = 8-blts 


LONGA 


OFF 




Ida 


Border 


;Grab border color 


and 


**I0 


;save upper nibble (RTC bits) 


ldy 


•Color-D&taSect 


;atore to Color record in data section 


eta 


(l.S).Y 
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Ida 


Border 


lnc 


A 


and 


no? 


era 


d,s}.y 


sta 


Border 


pep 


»*20 


LONGA 


OS 



:lncrement it (color Is lower nibble) 
;truncate any wrapping to upper nibble 
;0F with RTC bits 
;update the border 
;accumulator ™ 16-blt8 



This seemingly complicated series of instructions does one sim- 
ple task: It increments the screen's border color. It starts by going 
into 8-bit accumulator mode and grabbing the screen's border color 
register (also shared by the Real Time Clock chip in the upper nib- 
ble). The RTC bits are preserved and stored in the Color data byte 
via stack-relative indirect addressing. The border color register is 
fetched once again, incremented, and then the lower nibble of the 
result is logically ORed with the RTC bits. Finally, the new value is 
stuffed back into the border color register, and the processor goes 
back to a 16-bit accumulator. 

Most of this confusing footwork is due to the RTC bits needing 
to be preserved while the lower nibble of Border is incremented, all 
the while using stack-relative addressing. 



Any time a soft switch or $ExCxxx location is accessed, the 
accumulator should be set to eight bits. This is because the 
locations in this chunk of memory are mapped to eight-bit 
addresses. 



ldy 


•Cycle- 


DataSect 


;get Cycle record 


Ida 


(13).* 






dec 


A 




decrement It 


sta 


(l.S),Y 




:update counter 


bne 


Exit 




;lf counter Is not zero, exit 



This portion of the routine decrements a counter that keeps 
track of the number of times the border color changes. As defined 
in the data section, 64 iterations will pass before the counter 
reaches 0. When the sixty-fourth cycle is completed, the following 
shutdown code is executed: 



PUSHWOHD 

—IntSource 



•10007 



;Dlsable 1-eec Interrupts Ref Num 
iturn 'em off first 
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First, the source of the one-second interrupt is shut off. This 
must be done before the vector is restored in case another one- 
second interrupt occurs in the middle of this (unlikely, but it's bet- 
ter to be safe than reformatted). 



FUSHWORD 

ldy 

Ida 

pha 
day 
day 
Ida 
pha 
_S8tVector 



*I0018 
*01dVeot-DataSeot+2 

(i+2.s),y 



(l + 2 + 2.S),Y 



;Pu8h 1-bbc vaotor Hef Nun 
;puah nlgn word of old vaotor 



;(lndex low word) 

ip^sb low word of old vector 

xestore old 1 eeo interrupt vaotor 



The vector is restored to its original setting at this point. Notice 
how the byte constants in the stack-relative LDAs increase by 2 
each time more data is pushed onto the stack. This is because the 
program counter (plus data offset), initially pushed on the stack 
with the PER instruction, hikes up the stack each time something 
new is pushed, and of course, the reference must compensate for 
that. 



ldy 

Ida 
pba 
_HUnLockAll 



'CodelD-DataSect 
(1,3)J 



.push oode ID 
:unlock this blook 



As the last part of the shutdown sequence, the block that en- 
velops this code is unlocked so that it can be purged whenever the 
Memory Manager needs to use it. 

The DisposeHandle or DisposeAU functions shouldn't be used 
within the block being disposed. The code that follows the block 
could be reassigned to some other program in the computer, 
trashing the instructions and crashing the system. 

Exit pla jpull PC relative value off stack 

Remember, the 16-bit address of the data section of this pro- 
gram is still sitting on the stack, so it must be pulled off to main- 
tain harmony. 
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*$30 

OFF 

OFF 

*%00100000 

Soanlnt 



;8 -bit registers 



;clear 1-sec interrupt source 
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Once again, the computer is placed in eight-bit mode when the 
$ExCxxx space is being accessed. Storing $20 (%00100000) to Scanlnt 
resets the interrupt signal for one-second interrupts. If this is not 
done, the processor will be beaten by this interrupt source until the 
signal is cleared. (For fun, you can try leaving this out just to see 
what happens.) 

Also, recall that when the registers were saved at the top of 
this handler, the machine was in eight-bit mode. That means that 
only one byte per register is still sitting on the stack. 



ply 
Plx 
pla 
plb 
olc 
rtl 



;reatore registers 



;lnterrupt serviced, return 



After all the registers are restored, the carry flag is cleared to 
indicate that the interrupt was successfully serviced. The routine re- 
turns via an RTL instruction with all registers restored and the ma- 
chine still in native mode with eight-bit register widths, exactly as 
it was found at the beginning of this routine. 

Clearing Interrupt Sources 

Part of servicing any interrupt originating from the IlGS's built-in 
hardware or on a peripheral card is clearing the interrupt-generating 
signal. This is the only wav the hardware knows that someone has 
taken care of its interrupt. Once reset, the hardware can ready itself 
for new interrupts later on. If it isn't cleared, the hardware keeps 
the interrupt line on the microprocessor ringing nonstop. 



Note: Resetting an interrupt signal and disabling the source are 
two very different things. Disabling an interrupt source will 
turn it off completely, just like pulling the plug on your elec- 
tric alarm clock. Resetting the interrupt signal, however, is like 
hitting the snooze button. 



Unfortunately, there is no Toolbox function for clearing the 
built-in interrupt sources on the IIGS. Perhaps a future version of 
the Miscellaneous tool set will provide such a handy feature. 
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For now, your interrupt handler will have to access the hard- 
ware register area of the 1IGS directly to reset interrupt signals. An 
example of this is the program in the previous section. It stores $20 
to location SE0C032 (called SCANINT). This register contains two 
bits that correspond to the clearing of scan line and one-second in- 
terrupt signals. Writing a to bit 6 of SCANINT resets one-second 
interrupts. Writing a to bit 5 resets scan line interrupts. The other 
six bits are unused and should always be set to in writing to 
SCANINT. 

The following table identifies the interrupt reset locations in 
the Apple IIGS Softswitch register area: 

Address Name Description 

JE0C032 SCANINT Zero bit 6 to reset one-second interrupts; Zero 
bit 5 to reset scan line interrupts 

$E0C047 CLRVBLINT Write to clear vertical-blanking (VBL) and 
quarter-second interrupts 

SE0C048 CLRXYINT Write to clear mouse interrupts 

Interrupts from other sources such as serial ports can be 
cleared by fetching or storing data through the hardware's associ- 
ated data registers. 

The Loch Ness Keyboard Interrupt 

One myth about keyboard interrupts is just that: keyboard inter- 
rupts, They're a myth in and of themselves. They don't fully exist 
on the IIGS. The Apple IlGS keyboard really cannot generate an in- 
terrupt if, say, you press the M key. Some of the key sequences can 
cause interrupts, though, such as Control-Open Apple-Escape. But 
honest-to-goodness data interrupts from keypresses are mythical. 

At the moment, keypress interrupts are simulated by some 
trickery built into the Apple IlGS toolbox. In essence, when 
IntSource is used to turn on keyboard interrupts, a special task is 
invoked which runs in the background every 1/60 second. This 
task looks at the keyboard to see whether a key was pressed, and if 
it was, jumps to the keyboard interrupt handler installed via 
SetVector. Why go about it in such a sneaky way? 

Unlike most modern computers, which have keyboards that 
generate true interrupts from keypresses, the Apple IIGS was de- 
signed with the opinion that the extra bit of circuitry needed for 
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true interrupts could be sacrificed. But the IlGS's tools development 
team at Apple designed the Toolbox in such a way as to make a fu- 
ture upgrade of the hardware transparent to software. If a real in- 
terrupt-generating keyboard is available for the Apple IlGS 
someday, all programs that use SetVector and IntSource to establish 
keyboard interrupts will work just fine, and nobody will be the 
wiser (except you). 

In a HearlBeat 

Another form of task processing on the IlGS is provided by the 
HeartBeat Task Manager, part of the Miscellaneous tool set. These 
routines allow you to add a series of tasks to perform at any num- 
ber of 60Hz cycles. 



The HeartBeat Task Manager uses the vertical-blanking inter- 
rupt source, which interrupts every 1/60 second. 



A HeartBeat task is a routine, usually short, that begins with a 
special header identifying it as a HeartBeat task. The structure of 
this header consists of three fields, as shown in this example: 



TaskHdr 


anop 






TaskChaln 


dc 


14'0" 


:polnter to neit task 


TaskCouut 


ds 


1*60' 


number of 60Hz cycles before task Is run 


TaskSlg 


dc 


rtA56A' 


special task signature 



The TaskChain field starts out as a long value of 0. The Heart- 
Beat manager will change this to point to the next task in the 
HeartBeat task queue, should another be added later. 

Tlic TflskCuuiii wuiU Is d luuuiei Lliai Is tleeicLnciiicd by ilie 

HeartBeat manager every time the VBL interrupt occurs (every 
1/60 second). When this counter reaches 0, your task is executed. 
It's up to the task to reset the counter to the appropriate number of 
cycles before returning. Using this method, a task can run from 
once every 1/60 second to once every 19 minutes. 

Finally, the TaskSig word is a constant value of $A55A. If this 
value is not present here, an error code of $0304 (NoTaskSignature) 
will be returned when an attempt is made to install the task into 
the HeartBeat task queue. 
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Immediately following the task header is the code for the task 
itself. When the task is called, the computer is placed into native 
mode using 16-bit registers. The task terminates with an RTL in- 
struction, and unlike what happens with normal interrupt handlers, 
absolutely nothing needs to be preserved and restored before re- 
turning, You needn't fiddle with the carry flag, and even the regis- 
ter widths can be left modified without causing problems. Since 
your task is invoked indirectly by VBL interrupts, you don't even 
have to reset any interrupt sources. 

Indeed, this is the lazy person's way to install timed back- 
ground tasks. But there are some advantages to having all the 
nitty-gritty details handled for you. The only disadvantage is a pos- 
sible latency in execution of your task should there be a number of 
other tasks in the queue ahead of yours. 

Installing a HeartBeat task is simple. It's done by making a call 
to SetHeartBeat; 

Function: $1203 

Name: SetHeartBeat 

Places a task into the HeartBeat task manager queue 
Push: Address of task header (L) 
Pull: Nothing 
Errors: $0303. Task already in queue 

$0304, No task signature (or bad signature) 
$0305, Damaged HeartBeat queue 

As easy as using SetHeartBeat is for installing a task, the 
DelHeartBeat function is used to get rid of one: 

Function: $1303 

Name: DelHeartBeat 

Removes a task from the HeartBeat task queue 
Push: Address of task header (L) 
Pull: Nothing 
Errors: $0304, No task signature 
$0306, Task not in queue 

This chapter would be incomplete without mentioning a third 
HeartBeat function, ClrHeartBeat It removes all tasks from the 
queue. This should never be used by your applications, though. 






Function: $1403 

Name: ClrHeartBeat 

Removes all tasks from the HeartBeat task queue 

Push: Nothing 

Pull: Nothing 

Errors: None 

Comments: Don't make this call 

Using the program from the previous section as a starting 
point, Program 12-2 installs a HeartBeat task that cycles through 
the border colors for about a minute, The task then removes itself 
gracefully. 

Program 12-2. HeartBeat.ASM 



HeartBeat.ASM 



One-Secona Interrupt Demo 
Using K Heart &eat Tasn . 



A&SADDR ON 

KEEP Heartbeat 

MC0PY HB.nac 

Ham START 

phik 

plb 
.TLStartUp 

JITStartUp 
pha 

JWStartUp 
pit 

sta User ID 



:create this f-iie using HACGEN 



:84t* osnk = coat Dank 
:siart Tool Locator 
:slart Mlsc Tools 
; result space 
sstart Hemorv Manager 
:pull User ID 
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phi 


: result space 


PUSHVOPD ■SFOOQ 


;Type ID • Auk ID 


_<3etN«vID 


imaKc an ID 


pia 




Sts CooelD 




pha 


;rfs>ilt space 


pha 
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PUShXONG *SecEna-OneSec ;Siz« or oloe* 
PUSHVOPD CoaelD ;Cod*ID (or this handle 

ilocked, Fixeo, <purge*2' 
■, agar ess o! the block 

ion hanale 



PUStWDM 


■set ib 


PUSHLOKC 


■0 


JJeuHard 1 e 


Pla 




plx 




St* 





atx 




l as 


[0] 


5H 


BlKAoor 


lav 


■ 2 


in 


101, V 


at* 


3 kAou ••: 



;get long aaaress of Dlock 



PuSHLGNG lOneSec :Souree 

PUSHLONG BlkAaar jDestinatlon 

PUSHLONG iSecEnd-QneS*c I SIM 

_BlockMove i"»ve handler code 

PUSHLONC ainfcoor ;Poif>ter to HeartBeat task 
_SetHeartBeal 

PUSHVQRD »M002 ;En*ble VBL interrupt Ref Num 

IntSource :turn interrupts on 
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11 1 U-i j u[ji> 




PUSHVQRD User ID 


; shut down everything 




_»(ShutDovn 






JTTShutDown 






_TLShutDoim 






.QUIT OPanw 






UserlD ds 2 






QParms dc i4'0* 


iProDQS 16 Quit Code parameters 




oc isOOOCr 






• Interrupt Handler Code 


. 




i 


— • 




Border EQU »E0C034 


;RTC/Border color register byte 




Beats EOU 60 


.■Heartbeats per color change 




»•• Here a the tasic header: 






OneSec as * 


:tas« pointer storage chain 




BealCnt oc l Beats 


; approximately every secona 




ac i sA55A' 


:HeartBeat task signature 




«••■ Here's the las* code; 






LONG* OFF 


;This is the task's entry mode 




LONG I OFF 






phk 






PID 


:data Dank. * code bank 




rep isJti 


:16-Dit registers 




LONGA ON 






LONG! ON 






per Dat*S*et 


;push address o» data section to sue* 
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MP 


i»20 [accumulator = 8-bits 




LONG*. 


OFF 




Ida 


Border iGrab border color 




ana 


mFO -.save upper nioole CRTC Oits> 




lay 
st a 


iCoior-DataSecl istore to Color record in data section 
U.SKY 




Ida 


&oroer 

», [increment U Ccolor is lower nibble) 




ine 




ana 


■sOP ; truncate any wrapping to upper nlboie 




era 


O.SJ.Y ;0R with RTC Bits 




ata 


ftorder supdate the border 




rep 


i»2q :accumulalor • 8-btt 




LONGA 


ON 




lay 


■Cyele-DataSect ;get Cycle record 




Ida 


U.S1.Y 




dec 


A ; decrement it 




ata 


Cl .S>.Y (update counter 




bra 


Ex,t ||| counter is not lero, exit 




• Once we've 


cycled through the number ol Dorder changes specified. 




• we turn off 


VBL interrupts, retno** the HeartBeat task, and 




• unlock this 


memory block to make it purgeable when needed. 




PUSHVORD !iQ0D3 iDisaole VBL interrupts Ref Mum 




JntSource (turn 'moll first 




lay 


• BlkAddr-DataSecUZ spugh address ol task on stack 




Ida 


<1,S».Y |high-wora of aodress 




pha 






dey 






aev 


;C index low-word) 




la* 


tit2,si.V spush low-word of address 
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ilLLtliUpiJ — 




_telH#«rtBtftt 


;remove this task 




Idy 


■coo* id- eh usee 


t 




Ida 


CJ.S>.V 


ipush memory block ID 




Pha 








.HUnLockAII 


iunlock this Block 




■ -» - 




(Pull PC relative value off stack 




Per 


BeatCnl 


{Update Beat counter 




Id, 


10 






Ida 


■Beats 


preset HeartBeat counter for this taj* 




sea 


tl.SI.Y 






PU 




;pul 1 PC relative value 




rt, 




; then return 




DataSect 


ANOP 






Color ds 


1 


iTemporary color value workspace 




Cyc 1 e dc 


1 64 


jNwnber Of times oorder color changes 




CodelD 39 


2 


iUser-ID of this memory segment 




BikAddr ds 


4 


sAdaress of HeartBeat task header 




SeeEno A NOP 








" 
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The following things are new or different in the installation 
portion: 

• No vectors are preserved. 

• The task is installed with SetHeartBeat. 

• VBL interrupts are turned on. 

Simply installing a HeartBeat task won't make it go, The VBL 
interrupt source must be enabled as well. 

The task portion is substantially different from the one-second 
interrupt handler. First, it starts with a HeartBeat task header. This 
task is set to execute after every 60 heartbeats, which is approxi- 
mately one second. Notice that none of the processor registers are 
saved on the stack. This isn't needed for HeartBeat tasks. 

The guts of the routine are pretty much the same: Increment 
the border color, and see whether 64 border changes have been 
made. If 64 changes have been made, the VBL interrupt source is 
switched off, the HeartBeat task is deleted with DelHeartBeat. and 
the block of memory for this task is unlocked. 

Before exiting, the routine resets the task counter to 60 beats. If 
this isn't done, the task isn't ever called again, but remains in the 

queue. 

Finally, the task returns to the HeartBeat manager via RTL. 

Interrupt Caveats 

Here are a few important notes to keep in mind while working 

with interrupts: 

• The example programs in this chapter use little or no error check- 
ing. The intent was to keep the program listings as simple as pos- 
sible while presenting the study material. Your programs should 
rely heavily on error checking after each Toolbox call capable of 
producing errors. 

■ ProDOS calls and many Toolbox functions, especially those from 
disk-based tool sets, shouldn't he called from within an interrupt 
handler. Those resources might not be available at the time of the 
call. Instead, Apple recommends that such calls be installed into 
the Scheduler tool set's task queue. Information on that tool set 
was not available at the time of this writing. 

• Switching off an interrupt source from within an interrupt handler 
ts not a common practice, as in ui= iiiuaotat cc-v^u p»g»n<, 
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which can run in the background while in another application, 
turning off VBL interrupts can render the application useless if it 
depends on them. 

• You shouldn't use quarter-second interrupts. These are reserved 
for use by AppleTalk. 

• In general, use HeartBeat tasks for most timing-related interrupts. 
This is advantageous since it allows more than one such task to 
be present at the same time. 

■ Interrupt handlers are hard to debug with a runtime debugger. 
This is because the interrupts are occurring in realtime as you're 
stepping through the code. 

• If, while you're programming an interrupt handler, a test run fails 
and causes the system to crash, it's a good idea to reboot the 
computer. There's no telling what has become corrupted in 
memory. 

Chapter Summary 

Five Miscellaneous tool set functions are presented in this chapter: 

• SetVector 

• GetVector 

■ SetHeartBeat 

• DelHeartBeat 

• ClrHeartBeat 

Their official descriptions, including stack parameters and error 
codes, are discussed within the text of this chapter. 



_j 
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Desk Accessories 



According to the Apple Human 
Interface Guidelines, a desk ac- 
cessory is a small program that 
can be opened while another 
program is running. Good ex- 
amples of desk accessories are 
calculators, note pads, graphic 
scrapbooks, alarm clocks, utili- 
ties, and games. Just about any- 
thing found on your typical 
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(real) desktop is considered a desk accessory. 

In the Guidelines, Apple warns that desk accessories should 
never be too complicated. Some so-called desk accessories for the 
Macintosh are complete programs unto themselves: spreadsheets, 
word processors, and graphics programs. They go beyond the limits 
of desk accessories. Whether they are New or Classic, desk acces- 
sories should be quick, efficient, and helpful, short programs that 
make using the DeskTop interface more practical and enjoyable. 

This chapter is about desk accessories. It would be silly to de- 
scribe desk accessories in detail here, as if this were an introduction 
to the Apple lies. However, desk accessories are a common feature 
of the lies and Macintosh computers. They're just handy, memory- 
resident programs which are almost always available for use. Every- 
thing from the ever-familiar Control Panel to a modeless dialog 
box/alarm clock can be a desk accessory. 

Tell It to the DA 

When ProDOS 16 is booted, the desk accessories stored in the 
SYSTEM/DESK.ACCS subdirectory are installed into memory (see 
Chapter 3). There can be two types of desk accessories; the advan- 
tages of each will be discussed here briefly. The first type is a Clas- 
sic Desk Accessory (or CDA). This type is available at all times 
after ProDOS 16 is booted. Classic Desk Accessories can be chosen 
f,r.r* fkrt rnA menu hv nrpseino Cnntrnl-Qnpn Annie-Escape. For 
from the CDA menu by pressing Control-Open Apple-Escape, hor 

example, the Control Panel (where you set your various Apple IlGS 
options) is merely a Classic Desk Accessory, with the exception 
that it's part of your ROM and isn't loaded from disk. 

A New Desk Accessory (NDA) is only available to programs 
taking advantage of the DeskTop. NDAs are found in the Apple 
Menu in DeskTop applications where NDAs are specified. The 
FixAppleMenu ($1E05) function in the Menu Manager installs NDAs. 

The key difference between CDAs and NDAs is that CDAs are 
always accessible via Control-Open Apple-Escape, and NDAs can 
only be accessed by DeskTop applications that install them. Other- 
wise, all desk accessories stay resident in memory until you turn off 
the computer, reset by pressing Control-Open Apple-Reset, or run 
the ROM diagnostics by pressing Control-Open Apple-Option-Reset. 
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It's amusing how Apple has adopted this naming convention 
of New and Classic desk accessories. It's suspiciously similar to 
the Coca-Cola Company's marketing campaign which intro- 
duced a new formula for Coke a few years ago in order to 
compete more successfully with Pepsi (which, as you will re- 
call, a majority of people preferred in blind taste tests). After 
announcing the New Coke, they dubbed the original concoc- 
tion Coca-Cola Classic. This is of particular interest because 
Apple Chairman John Sculley was lured away from PepsiCo 
(the people who produce Pepsi Cola) to work for Apple Com- 
puter. Just a coincidence? Apple claims it is. 



Since desk accessories are memory-resident, they're usually 
written in machine language to make them as compact as possible. 
In fact, because of the structure of desk accessories, it's almost im- 
possible to write them in a high-level language unless the compiler 
has special provisions for developing them. 

Some high-level language compilers do make special allow- 
ances for desk accessories. The TML Pascal system has a special di- 
rective that places the desk accessory header information at the 
front of your Pascal code. This way, most of the information is 
handled by the compiler, and your job is simply to write the desk 
accessory. 

Writing a desk accessory is just like writing a normal program. 
In fact, just about any ordinary program can be turned into a desk 
accessory simply by adding a bit of extra information and changing 
the filetype to $B8 for an NDA or $B9 for a CDA. (Note that the 
extra information is what's important. Simply changing a filetype 
does not make a desk accessory.) 

The steps to creating your own desk accessory differ only in 
the type of desk accessory you're writing. The following sections of 
this chapter detail the processes of creating a Classic Desk Acces- 
sory and then a New Desk Accessory. 

Classic Desk Accessories (CDA) 

Of the two types of desk accessories, the Classic Desk Accessory is 
simpler to program. CDAs are easy to create for two reasons. The 
first is that they are text-oriented. CDAs pop up on the familiar old 



40- or 80-column text screen. You don't have to worry about 
graphics. The second reason is that they usually don't rely on DOS. 
Because CDAs can be used at any time, regardless of which operat- 
ing system is running (ProDOS 8 or 16, DOS 3,3, Pascal, CP/M, or 
no DOS at all), disk-related functions should be avoided. 

It should be noted that if your CDA involves disk activity, it 
needs to make sure the appropriate DOS is in memory. An Apple 
IlGS can have a CDA in memory and run another operating sys- 
tem. Never assume ProDOS 16 is present when, in fact, a CP/M 
program could be running. 

If your CDA requires disk activity, it should be able to identify 
the current DOS environment and inform the user if it's unable to 
operate. 

A Classic Desk Accessory begins with a special header. The 
header is basically text string information and pointers. For a Clas- 
sic accessory, the header consists of a title and two long-word 
pointers: 

MyCDA air "CDA Title" ;name of DA Id the CDA menu 
do 14'StartUp' ;polnter to Btartup routine 
dc 14 'CleanUp' ;polnter to a clean up routine 

It may strike you as odd that this program begins with a text 
string. If you're sitting there wondering how the CDA can run, re- 
member that CDA files have a special filetype that lets ProDOS 
know how to load and run them. For Classic Desk Accessories, a 
filetype of $B9 is used. Disk directories show this as a CDA 
filetype. 

The CDA's title is a standard Pascal string (beginning with a 
count byte that tells the length of the string). Though it can be as 
many as 32 characters long, the title should be as short as possible 
while still being descriptive. 

The long pointer to the StartUp routine is actually the address 
where the CDA code (program) begins. The routine at StartUp is 
called in full native (16-bit) mode, and it must preserve both the 
stack pointer (SP) and the data bank register (DBR). The routine 
must end with a long return (RTL). Those are the only rules to fol- 
low. The essence of the CDA resides in this routine. 

The long pointer to the CleanUp code contains the address of 
a routine used to clean house. Whenever the DeskShutDown func- 
tion is performed, this routine is called. This happens whenever 
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ProDOS 16 switches to ProDOS 8, or vice versa, and whenever an 
application makes the DeskShutDown call. 

In practice, the CleanUp subroutine should be used to close 
files, remove interrupt handlers, and do whatever is needed to 
clean up any mess the CDA may have made. Like StartUp, this 
routine returns via an RTL Even if there is no CleanUp routine re- 
quired by your CDA, the pointer must point to an RTL instruction. 

NUMCONV.CDA 

The following is a complete Classic Desk Accessory program. After 
assembling it, change its hletype to $B9 and copy it to your 
ProDOS 16 disk's SYSTEM/DE5K.ACCS directory. To install it, 
just reboot. Then, when you need a handy hex or decimal number 
converter, it's only as far away as Control-Open Apple-Escape. 

It might be added that this program is somewhat limited in its 
capabilities. Astute IIGS programmers will find ways to fix up this 
code or to use it as a skeleton for their own CDAs. 

Program 13-1, Number Converter CDA 



• Numoer Converter ■ 
» Classic Desk Accessory De*o ■ 



ABSADOR 


ON 




KEEP 


NunConv .CM 




HCOPY 


NunConv .HAC 


(Create this lite with MACGEH 


NuraConv START 






sir 


•Nuneer Converter' :Name of CDA in menu 


dc 


^'Startup" 


;Poifit*r to starting routine 


ac 


ii Cleanup 


■.Pointer to clean up routine 


Sure Up ANOP 






phb 




:save oat a Dank 


Ph* 




mow make oats Dank = coo* Dan* 


Pi D 










_Te»t Reset 

push. long iTitle 
jfritecstring 

Loop push long tprorapt 
JrfnteCString 

pha 

push long alflBuf 
pushvioro ale 
pushword **BD 
pushirara ■! 

.ReaaLine 
poilword Count 
Wfl Ex 1 1 



i ax 
laa 

and 

Deq 



jsr 

BCS 



■0 

maui 

»I7( 



«2 

(ProcTOi.xi 

Loop 



si a NTvpe 

push long SResult 
_tfriteCString 
or a Loop 
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; initial ize text 1/0 



idraw ti tie 



iprompt tor input 



; result space 

ipointer to input cutter 

inumtor ol characters max to reaa 

:Return key INSB set; is EOL character 

;Echo input 

iget the I me 

I get character count 

•,n equal to zero, exn 

; assume hex 
scheck tor hex 



i convert it 

i index decimal converter 

I call ealher Hex2uec or Dec2Htx 

iprooably strmo overt lou 

schanoe result prefix 
ipoini to string to print 

:go back lor «iore 

irestore Dank 
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Cleanup ANQP 


:Ho clean up needed here 






rtl 


;return to COA menu here 






HexZDec push long 10 


;result space 






pusnlong ilnBufH 


:Point to string (skipping 1} 






Ida Count 








dec A 


i length is Count minus 1 (the *) 






pha 


i length ol siring 






_Hex2Long 


;long is On the suck nou 






push long lOutBul 


ipoint to output Dufter 






pusnuora • 10 


; output string length 






pushvord '0 


; unsigned 






.LonoZDec 








104 l*A0nD 


itwo spaces 






ris 








Dec2Hex push long " l - 


i result space 






pushlong ilnBut 


;pomt to String 






pushworo Count 


:number of chars 






pushuora iO 


lunaignM 






_Dec2Long 


sLong value is on stack 






push long sOutbul 


ipoint to output Duller 






pushvord ilO 


; output string length 






_Umi02Hh 








1 04 MA-MO 


: space r aol lar sign 






rts 








DMi s*CHOn 


• 






ProcTDl dc i'Hex2Dec- 








ac I Dec2Hex- 








Count as 2 






j 


I n Bo t as lb 




315 











Result dc 


•1c .c — > 


WType os 


2 


Out&ul oc 


10c- ' ' .il 13.0 


Title ac 


il '12,17, IS ,vc 


dc 


B'l I Numfcer Converter 1 1' 



Prompt ae 
END 



9c , ik'14, 13,13' 

?C ' .c'Prew RETURN alone to quit- ,ir IS" 

re .c ( Start hex numbers ui th »>'. i I' 13. 13.0- 

ir 13' .c'Numeer: ' . 1 1 ' • 



- 



If you plan to make extensive use of this desk accessory, 
you're advised to write a custom input routine, The ReadLine tool 
is adequate for getting a line of input, but doesn't allow any editing 
capabilities. For example, if you enter a mistake, pressing the back- 
space key (-) will not erase the mistake. It will insert an ASCII 8 
into the input stream, causing the result of the conversion to be 
invalid. 

New Desk Accessories (NDA) 

The formula for producing New Desk Accessories involves more 
ingredients than the Classic formula requires. Keep in mind the dif- 
ferences between the environment of the NDA and the environ- 
ment of the CDA. For example, because you're in the DeskTop, it's 
expected that your NDA will use some form of DeskTop conven- 
tion. This step alone results in a higher level of programming diffi- 
culty than that of creating the CDA. 

NDAs are accessible whenever a ProDOS 16 DeskTop applica- 
tion is running in the super-hi-res 320 or 640 mode and the Apple 

...».,.. 1.. UlAUUltkl 1..^ .l.w -,-i- A.1IW I-—- «•-'! — •■-- n» » 

can assume that these tool sets are active and started up: 

• QuickDraw 

• Event Manager 

• Window Manager 

• Control Manager 
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• Menu Manager 

• LineEdit 

• Dialog Manager 

• Scrap Manager 
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Of course, the Tool Locator, the Miscellaneous tool set, the 
Memory Manager, and other ROM-based tool sets are also avail- 
able and do not require starting up or shutting down. 



No direct page space is allotted to the NDA, so it must be ob- 
tained by calling the Memory Manager's NewHandle function 
or by tricky use of the stack. The Magnifier program near the 
end of the chapter contains an example of this. 



Like the Classic Desk Accessory, the NDA begins with a spe- 
cial header. (Also like its Classic counterpart, an NDA file can't be 
run directly, so it's assigned a filetype of SB8, shown as NDA in di- 
rectory listings.) 

The NDA header contains seven fields: 

MyNDA 



do 


W'OpenNDA' 


Open the NDA routine address 


do 


14-CtoseNDA' 


Close the NDA routine addreee 


do 


WTheAatlon' 


Do the NDA action routine 


do 


14'InlHJDA' 


Inlt NDA Startup or ShutDown 


do 


l'lOOOO' 


HeartBeat counter 


do 


I'trtir 


Event mask 


do 


o'— NDA KameXH'.SirO' 


NDA Item name In Apple menu 



The first four fields are pointers to subroutines. Each of these 
special routines is called by the Desk Manager as needed. They 
must preserve the stack and data bank registers, and end in RTL 
instructions, In addition, they must preserve the current GrafPort if 
it is swapped out. Each routine is described in more detail below. 

The word value following the pointers is like a HeartBeat 
counter. (See Chapter 12 for details on HeartBeat tasks and inter- 
rupts.) Its value determines the number of 60Hz cycles that will 
pass before the NDA's Action routine is called with the Run code 
(more on this below). If this value is 0, the Action routine is called 
every pass (actually, every time the TaskMaster loop is executed in 
the DeskTop application), Unlike a HeartBeat task, the NDA does 
not need to reset this counter after each pass. 
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Next, a word containing an event mask is used to specify the 
types of events that the NDA can handle as they relate to actions 
concerning the NDA. The bits in this word correspond to TaskMas- 
ter Event Codes introduced in Chapter 12 of Mastering the Apple 
UCS Toolbox. 

The last field contains a text string in the format of a Menu 
Manager menu item line, It begins with any two characters, fol- 
lowed by the title of the NDA. The item line is terminated by \H 
and three zeros. The first two zeros are filled in by the Menu Man- 
ager with the item's ID number. The last zero is just a normal C- 
string terminating character. 

The four special routines are described next. For real-life exam- 
ples of these procedures, see Program 13-2. 

The NDA Open Routine is called by the Desk Manager when 
it wants the NDA to create its window. In fact, the Desk Manager 
expects the Open routine to return a window port pointer on the 
stack, and provides result space for it. This is perhaps the trickiest 
of the four special routines, because the Open subroutine has to 
modify result space on the stack with the window pointer infor- 
mation. (You'll have a good feel for how result space is changed to 
meaningful values by the Toolbox after dabbling with this func- 
tion.) The example NDA program below demonstrates this hair- 
raising procedure. 

After the window is open, the Open routine should set a flag 
indicating that the window has been created. 

The NDA Close Routine is called whenever the close box on 
your NDA's window is clicked, or whenever the Close menu item 
(ID = 255) is selected. Your NDA's Close function is used to close 
the window created by the Open routine. It should test the flag set 
by the Open routine, then close the window if it's open. Also, it 
should perform any other housekeeping tasks necessary to close 
down the NDA gracefully. 

The NDA Action Routine is responsible for dispatching a host 
of handlers to service the events related to the NDA. When called, 
the Action routine will find a special code in the accumulator 
which corresponds to the type of action that took place. The nine 
Action codes are shown in Table 13-1. 
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Table 13-1. Action Codes 






Code 

1 



Type 
EventA 



Cursor 



Menu 



5 


Undo 


6 


Cut 


7 


Copy 


8 


Paste 


9 


Clear 



Description 

DeskTop event that affects the NDA has taken place. 

Use the X and Y registers to obtain the address of the 

event record to further interrogate the event. (X contains 

the low-order word and Y contains the high-order word 

of a long address.) 

It's time to run the guts of the NDA. (See the description 

of the HeartBeat counter field above.) 

If the NDA window is open, this code is passed to your 

Action handler each time TaskMaster is called. This is 

useful for changing the shape of the mouse pointer when 

it's moved into your NDA's window or some other area 

on the DeskTop. 

A menu item has been selected. The Menu ID and Item 

ID are passed in the X and Y registers respectively. 

Undo selected from the Edit Menu 

Cut selected from the Edit Menu 

Copy selected from the Edit Menu 

Paste selected from the Edit Menu 

Clear selected from the Edit Menu 

These last five codes correspond to editing functions your 
NDA may want to handle. If not, the NDA places a zero Into the 
accumulator and returns. Otherwise, the NDA handles the editing 
action appropriately and returns with a nonzero value in the A 
register. 

The NDA Init Routine is run whenever DeskStartUp or Desk- 
ShutDown is called by an application or by the operating system. If 
DeskStartUp is called, the Init routine will find that the accumulator 
contains a nonzero value. In this case, the NDA can do whatever it 
needs to do to prepare itself (usually nothing). If DeskShutDown is 
called, the Init routine will detect a zero value in the accumulator. 
It can then clean house as appropriate (for instance, it will close the 
NDA's window if it's still open). 

MAGNIFY.NDA 

The following program is an excellent example of a New Desk Ac- 
cessory. When installed and selected from the Apple menu in a 
DeskTop program, this NDA will bring up a small window on the 
screen. It magnifies 512 pixels (a 32 X 16 pixel area), at the mouse 
pointer's location, and draws the enlarged pixel map in its window. 
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It demonstrates the structure of a simple New Desk Accessory. 

This will run in 640 and 320 modes, though the aspect ratio 
for 320 mode is a bit out of proportion (the window appears twice 
as wide as in 640 mode). The budding programmer will want to 
keep the different screen resolutions in mind when creating an 
NDA. 

Program 13-2. Magnifier NDA 



» Hagn 


fier 


• 






■ New Desk Accessory Demo 


■ 






ABSADDR 


ON 








KEEP 


Hagn i f y 








KCOPY 


Magnify. HAC 






;Create using NACGEN 


Magnify START 










de 


H'OpenNDA- 






lOpen the NDA 


ac 


H'CloseNDA" 






;Cloae Che NDA 


dc 


l4'Th*ACCIOft' 






;Do the NDA action 


DC 


iVImtNDA' 






llalt NDA Startup or ShutDown 


ac 


isoooo- 






iHeartbeat counter: ■ each beat 


de 


l' •Hil- 






;Event mask: tfttt = all events 


oc 


ls' — Hagmfjervh" 


3j]'0- 


;NDA item name in Apple menu 


» Open the NDA (if closed) 









UpenNDA ANOP 
PhD 
phfc 

pit) 

320 



isave data bank 1*1 byte to stack) 
:cata bank ■ code Dank 











dlc OpenFlag 


iHave ue already created the window? 




Dmi Opened 


tyes -- so skip this stuff 




Pha 


iResult space 




pha 






push long iWmoowRec 






.HewWinoov 


iCrUtt Che NDA window 

:Leave winaow port pointer on stack 




laa. 1.9 


;Get window pointer t low Byte > in stack 




sta VindcwPtf 


iSave in neoory, ana 




sta 4*1+4,3 


! Rep lace result space on stack 




lad 1*2.S 


;Cet winaow pointer thigh Dytei in stack 




sta WmoouPtr->2 


-.Save in memory, ana 




sta 4+1*4*2,3 

I 


; Replace result apace on stack 
nBecall. WindovPtr is on stack) 




_SetSys¥inow 


iflarie this as a system window 




dec OpenFlag 


K-U Flag win flow as open 




Opened pin 






PCI 






• Init NDA StartUp/ShutDown 


♦ 




; On entry, accumulator is zero if DeskStartUp called, 




s Else the A-reg is non-iero 


f DeskShutDown was called. 




lnitNDA ANOP 






tax iTeat 


accumulator^ DeskStartUp cal lea? 




Dn* AnRTL ryes 


- else fall into NDA cles* routine... 
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Close the NM (if not op*n> • 



CloseNOA 


AKQP 


phb 




phk 




pit) 




Olt 


OpenFlag 


Dpi 


CI Med 



push long VindowPtr 
_CloseWi.naov 
six OpenFlag 



Closea plt> 
AnRTt rtl 



The Act ion 

PhD 
Phy 
phx 



plD 

ate A 

43 1 A 

tax 

jsr lProcTbl.X> 
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-.save data Bank 

:<Ut4 bank ■ code bank 



Ms the window opened? 
;no — already closed 



;Close it 

:flag it closea. too 



irestore aata B*nk 



Handle NDA Action Event • 



;save data bank 

;Save X and Y laoaress of Event Record* 



jtA-s rang* is |.,9, make it p. .8) 
; index procedure table 



; Handle the NDA action event 



1 



PU 






; Rest ore X,.. 


ply 






:...and Y... 


plO 






; . . . and DBS 


rtl 








NDAUndo 


ANOP 




:W« don't handle any of these actions 


NDACut 


ANOP 






NDACopy 


ANOP 






NDAPast* 


ANOP 






NDAClMr 


AHOP 








Ida 


■0 


iflag. the aoove as not handled 


NDAHenu 


AHOP 






NDACursor 


AHOP 
rts 






NDAEvent AN0P 






;»2 bytes on stack (return address? 


phfl 






-,'2 bytes to stack 



tea ;DP » 3P (tncky way to get DP access) 

Ida [2«2+ll :Grab Event "What" code from stack 

crop «9 ;Event codes less than * supported here 

ocs CtEq9 !»> *. 90 skip this 

asl A ; index into eveni procedure taole 

tax 

jsr cEventTci.X) ;call the event handler <upoate 0m y) 











AutoKet- 


ANOP 




Act ivate 


ANOP 




NotlttM 


rts 




Update ANOP 






push! 


ong WmoowPtr 





_Beg in Update 

jsr HDARun 

pushiong WindowPtr 

_EndUpdate 

rts 



:Set VigRgn 5 Update region 



iHagmty screen area at mouse location 



; empty update region 



a Mam NDA "Run" Event » 

* — — — -- — « 

NDARun ANOP 

push I ong iCurrPt 

_GelHouse 



:get current mouse location 



Ida CurrPt :corapare current and prew ious points 

emp WorkPt 

Ida CurrPt»2 itcould use EqualPt. but this is fasten 

abc workPt«2 

one Explode ;it not equal, explode some pixels 



GtEq9 p|d 
rts 
House Down ANOP 

flousellp ANOP 

EtyDovn anop 



^Restore direct page 
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L. 



;elae just return 



Explode rooveleog CurrPl.VorkPt :set points 



pushiong tfindovPtr 
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_SlartDrawmg ;Draw in NDA window 






9H NmY ;imt V rectangle coordinates 






stz NaxY 






movevora il6. VCount ; Explode 16 lines oown 






_Hio*Cor90f ;turn oil the pointer 




VLoop 


stz MmX unit rectangle >: parans 
stz. MaxX 

me HaxY saajust Y coora rectangle 
inc H«Y ;»2 






movewora CurrX.Xposn ;reset X posn 
novewora »32.HCount smit honz. counter 




HLoop 


pha ; resu 1 t space 

push long WorkPt 

_fletPixel :orab the pixel at current X,Y point 

_SetSol idPenPat ;set the pen color to it 

aoo M.HinX.MaxX 

push long •TheRett 

.PaintRect idrau the rectangle 

movewora HaxX.MinX inext olock over 

i nc XPosn 

oec HCounc 

one HLoop 

novewora MaxY.HinY inext line Oown 
i nc YPosn 
dec VCount 
one VLoop 

.ShouCursor :turn cursor Back on 

novelong CurrPt. WorkPt icopy points ior next pats comparison 

rts 
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Data Section 



TneReet 


ANOP 




HinY 


as 


2 


fllnX 


as 


2 


MaxY 


da 


2 


Max* 


as 


2 


VCount 


09 


2 


HCount 


as 


2 


WorkPt 


ANOP 




YPosn 


09 


2 


XPosn 


da 


2 


CurrPt 


ANOP 




CurrY 


as 


2 


ProcTBI 


ac 


, 



lexplooea pixel rectangle 



:explosion counters 



ac 


iNDAEvenf 


ac 


rNOAPun- 


oc 


i NDACursor 


oc 


rNDAHenu 


ac 


I'NDAUnao' 


ac 


i NDACut' 


oc 


rNDACopy 


CK 


I'NDAPaste" 


ac 


i-KOACIear' 



icurrent mouse coordinate point 

:NDA event handier 

jactuai NDA coae <gutsJ 

;the rest ol these are unusetf 



ac i Notllsea' s nothing 

AC I 'Nous* Down' i House Oown 

ac i MouseUp : House Up 

Oc I'KeyDown' : ley Down 
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Dr 


sk Acce 














oc 


r Not Used' 




1 nothing 




« 


1 ' Autoley ' 




i Auto Key 




ac 


1' Update ' 




; Update * (only one handled) 




* 


I'NoUisea" 




; nothing 




ac 


■'Activate' 




; Activate 


DpenPUg 


as 


2 




;Boolean; NBA Wmoow open, (lag 


Winaowptr 


as 


4 




■GrafPortPtr: Vindou port pointer 


vTitle 


str 


'Hagni £y" 




■Title of NDA vindou 


WinoovRec 


ae 


i ' vpecEnd-w i naouStc • 


:Size of parameter cable 




QC 


■ \i looooooioioooao- 


■Vindou frame oi ts 






oc 


H'uTi tie' 




■Pointer to title 






oc- 


|4'0' 




iKtfCOfl 






ac 


■0,0,0.0- 




■ Zoom rect 






ac 


IVO' 




iColor taDie pointer 






ac 


1-0,0' 




■ Origin CY 8, X> 






ac 


■ 0,0 




■Data area (V i H> 






Oc 


1*0.0' 




■ Grow box max (V 4 HI 




ac 


I'M' 




■Scroll range CV & H> 




ac 


■'0,0' 




■Paging range (V & to 




ac 


|4'0 




■ Info Dar Re f Con 




ac 


i0' 




■Info Dar height 




Oc 


i4Q 




:D*fi(iiCion procedure 




ac 


|4'0' 




■ Info oar draw routine 




ii- 


l4'0' 




■Content or aw routine 




dc 


1-40. 80. 72 


176' 


■ Poai tiofi 




ac 


H'-T 




■Topmost plane 




ac 


14*0' 




■Window storage pointer 


WRtcBna 


wrap 

END 
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Chapter Summary 

All the tools found in the programs in this chapter are discussed in 
detail in other chapters of this book, as well as in Mastering the Ap- 
ple IIGS Toolbox. None of them deal exclusively with the Desk Man- 
ager, however. 



328 



Chapter 14 

ProDOS 



Although this book is about 
mastering advanced program- 
ming techniques for the Tool- 
box on the Apple IIGS, without 
ProDOS such a mastery would 
be nearly impossible. Though 
they sound like two different 
beasts, ProDOS and the Tool- 
box often cross paths. For ex- 
ample, ProDOS is used by the 
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Standard File Operations tool set. Font Manager, and the Tool Lo- 
cator. Those tool sets rely upon ProDOS to perform many of their 
functions. 

The Operating System 

The Professional Disk Operating System, dubbed ProDOS, is little 
more than a handful of commands to manipulate disk drives. It 
isn't really an operating system in the classical sense, but it is a 
smart software interface between an application and a storage 
device. 

Fully detailing the workings and command structure of 
ProDOS is beyond the scope of this book, so this chapter will have 
to serve simply as an introduction to ProDOS 16. In it, you will see 
how to perform a ProDOS command in machine language, C and 
Pascal. Included are two lengthy sections that list the ProDOS 
commands and their parameters. The Standard File Operations tool 
set is also covered, and a sample program in machine language, C, 
and Pascal gives you a working example of how ProDOS is used in 
a real-life situation. Finally, the chapter is wrapped up with a list of 
ProDOS 16 error codes. 

Other Texts 

If you're familiar with the way ProDOS 8 or other disk operating 
systems work, you'll find this chapter a useful reference, But, if 
you've never worked with file management, it's suggested you 
check out a programmer's tutorial to working with ProDOS. Some 
books worthy of mention are 

Apple IIGS ProDOS 16 Reference, Apple Computer, 1987. Addison- 

Wesley. 
Beneath Apple ProDOS. Worth and Lechner, 1984. Quality Software. 

A note to ProDOS 8 programmers. You're probably familiar 
with ProDOS 8, the eight-bit version of ProDOS released by Apple 
Computer in late 1983. ProDOS 8 is the operating system that cur- 
rently hosts the majority of software for the Apple II series of com- 
puters, including such popular programs as AppleWorks. But, since 
ProDOS 8 is geared toward the 64K architecture of earlier Apple 
lis, it's inadequate for working with the great expanses of memory 
and features of the Apple IIGS. ProDOS 16 takes full advantage of 
the memory you have installed in your computer. 
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Programmers well versed in the workings of ProDOS 8 will be 
relieved to know that ProDOS 16 is similar to ProDOS 8 in most 
respects and is better in many. It's Tar easier to program than 
ProDOS 8, even though it's more sophisticated. Function calls are 
made in a familiar manner, the carry flag indicates that an error oc- 
curred, and so forth. 

There are many new features along with the baste familiarity. 
Among other things, parameter tables no longer begin with a count 
byte. It was the intent of ProDOS 8 to verify the parameter table 
for a call by making sure the count byte was correct. In a way, this 
is useless, because the program will probably crash whether the 
count byte is wrong or the parameter table is referenced incorrectly. 

Some of the calls have been renamed, simplified, or have 
slightly different parameters. Some new calls have been added to 
make disk operations and file management easier than ever before. 

A Call to ProDOS 

Before you can use the functions in ProDOS 16, you must first boot 
a disk formatted and set up for ProDOS 16, such as the System 
Disk you received when you bought your IICS. (See Chapter 3 for 
details on how a ProDOS 16 disk is set up,) 

Once loaded, ProDOS 16 can be accessed from machine lan- 
guage by making a long jump to a subroutine at location $E100A8. 
For example: 

Jel JE100A8 

This address is known as the ProDOS 16 Machine Language 
Interface (MLI) vector. Calls to the MLI vector are made in full na- 
tive mode. Your program should preserve the accumulator because 
ProDOS 16 will store an error result in the A register after each 
ProDOS call is made. (More on this later.) All other registers are 
preserved. 

A call to ProDOS is followed by two arguments: 

• A command number (word) 

• A pointer to a parameter list (long) 

These arguments are discussed later in this chapter, but, for 
now, here is a typical ProDOS 16 call: 






jsl IE100A8 
do r$29' 

do 14'qPa.rms' 



;Call the ProDOS 16 MLI 

;429 = "Quit" command number 

-.long pointer to parameter Hat 
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It might appear to be insanely dangerous to use this format for 
a function call. You would think that after the JSL, the program 
counter would return to the arguments and careen straight into bit 
limbo. But in fact, ProDOS 16 will adjust the program counter so 
that it safely returns to the instruction following the long pointer 
argument. 

This means that you must always call the ProDOS 16 MLI via 
a JSL instruction, and six bytes of argument information must 
follow. 

Calling ProDOS from Machine Language 

As shown in the previous section, calling ProDOS from machine 
language is done by performing a JSL to SE100A8, followed by two 
arguments. But the call can be simplified at the source level by 
using assembler macros. The APW Assembler's M16.PRODOS 
macro file contains macro definitions for every ProDOS 16 
function. 

Like tool calls, ProDOS 16 macros begin with an underscore, 
followed by the name of the ProDOS command. The argument to 
the macro is the address of the parameter list. As an example of 
using macros for doing a ProDOS call, here's the ProDOS 16 Quit 
function in APW assembler format: 

_QUIT QParnw .ProDOS 16 quit function call 

;meanwhll8. somewhere else In the program: 
QParma dc 14'0" ;longword of zero (no chaining) 

do l'O' ;word of zero (no returning) 

The _QUIT macro actually expands to the equivalent assembly 
language statements shown here: 

Jsl 4E100A8 

do 1-*2G' 
do 14'QParmB" 

It's obvious that macros can clean up your ProDOS 16 instruc- 
tions as well as they do for Toolbox calls. 

Calling ProDOS from C and Pascal 

Even though C and Pascal have their own built-in disk functions as 
part of their languages, your high-level programs can access 
ProDOS directly. The advantage is faster, more efficient programs. 
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The disadvantage is that your programs will be incompatible when 
ported to other computer environments. However, since your Desk- 
Top applications perform tool calls and other lies-specific opera- 
tions, it's probably safe to assume that source code compatibility 
has already been tossed out the window. 



A general note to C programmers: If your programs can avoid 
using any of the standard C library functions, including C's 
disk-related commands such as fopen( ), your executable pro- 
gram will be many times smaller. 



To make a ProDOS call in C, your program should include the 
prodos.h header file at the top of the program; 

♦include <prodoB.b> 

This header file contains predefined symbols for error code num- 
bers, parameter list structures, and the ProDOS function call 
macros. 

To perform the ProDOS 16 Quit function in C, the following 
statement can be used: 

QUITC ftQPtroi ); 

Each ProDOS function call in C follows the naming conven- 
tions of ProDOS 16: The names of the C functions are the names 
of the ProDOS 16 commands, and they're always in capital letters. 

A ProDOS command in C requires just one argument: the ad- 
dress of the parameter list. The list is usually a structure containing 
the needed information to perform the call. Don't forget to place 
the ampersand (&) in front the structure name, or your program 
will crash. 

In order to use ProDOS in TML Pascal, include the ProDOS 16 
unit symbol file in the USES portion of the program: 

USES QDIntf, 
GSIntf, 
ProDOSlQ. 
MlecToola; 

This makes all the ProDOS 16 functions available to your pro- 
gram. However, naming conventions for ProDOS 16 calls in TML 
Pascal are not as consistent. They all begin with "P16" and do not 



include underscores. The Quit call in TML Pascal is 

P16Parma.cliaLnPalh := StrlngPtr(O): 
PlSParms.returnFlag := 0: 
P18Qult( P16Parms ); 

Unfortunately, the arguments to the call are not straightfor- 
ward either. All arguments to ProDOS calls in TML Pascal are ref- 
erenced through a variant record, called P16Parms in the above 
example, which is of P16ParamBlk type. Before a call can be made, 
the fields in the parameter list record must be filled. Setting up pa- 
rameter lists is discussed later. 

Checking for Errors 

After each ProDOS call, and depending on which language you're 
using, you can check for errors: 

Language Check for Errors 

Machine language Examine the carry flag 

C Check a variable 

Pascal Test the result of a function 

In machine language, if the carry flag is set, an error has occurred, 
and the accumulator will contain an error code number, as you 
came to expect in Toolbox calls. For example: 

;oall the ProDOS 16 MLl (4E100A8) 

:functton number 

parameter list pointer 

;lf carry is clear, no error occurred 

;branch to error handler If carry set 



jsl 
dc 
dc 
bcc 



Jmp 



ProDOSieMLl 
I'READ-BLOCK" 

WHBParma" 
NoError 

HandleDlslcErr 



NoErnor 



In C, the _toolErr global variable holds a nonzero value after 
making a ProDOS 16 call if an error occurred. The value in 
_toolErr is the ProDOS 16 error code number. 

READ=BL0CK( fcRBParmu ): f Make the ProDOS 18 call '/ 

If ( -toolErr- ) /' If an error occurred. . . */ 

HandleDlskErr( ); /• . . .handle It. «/ 

With TML Pascal, a nonzero value returned by the lOResuIt 
function indicates that an error occurred. Any positive, nonzero 
value is a ProDOS 1 6 error code number. 
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p..nnF 




~ ~ riou^Jj 




PlSReadBlockC P16Parms ); { 


Make the ProDOS 18 call ) 




IF IOReeuIt > THEN { 


If an error ocourred. . . } 




HandleDlskErr; { 


then handle It. | 






Error codes are provided at the end of the chapter. 




ProDOS 16 Functions 






Tab 


e 14-1 is a list of the function names and numbers supported 




by ProDOS 16 Version 1.3 


, along with a short description of each 




command. 






Table 14-1. Functions Supported by ProDOS 16 




Housekeeping Functions 






$01 


CREATE 


Creates new files or directories 




$02 


DESTROY 


Destroys files or empty directories 




$04 


CHANGE-PATH 


Ri-names a file or directory, or moves its 
link 




$05 


SET_FILE_]NFO 


Sets various attributes to a file 




$06 


GET_FILE_INFO 


Returns the information set by 
SET-FILE-INFO 


. I 


$08 


VOLUME 


Returns information about a disk volume 




$09 


SET_PREFIX 


Sets one of eight possible prefixes 




$0A 


GET-PREFIX 


Gets one of the eight internal prefixes 




$0B 


CLEAR_BACKUP_BIT 


Clears the backup bit on a file 




File Access Functions 






$10 


OPEN 


Opens an existing file for reading or 

writing 




$11 


NEWLINE 


Specifies the newline character when 
reading 




$12 


READ 


Reads data from an opened file 




$13 


WRITE 


Writes data to an opened file 




$14 


CLOSE 


Closes any or all opened files 




$15 


FLUSH 


Writes any unwritten data to a file 




$16 


SET_MARK 


Changes the current position in a file 




$17 


GET_MARK 


Returns the current position in a file 




$18 


SET_EOF 


Sets the end-of-file position for a file 




$19 


GET-EOF 


Gets the end-of-file position for a file 




$1A 


SET_LEVEL 


Sets the system file level for subsequent 
access 




$1B 


GET_LEVEL 


Gets the current system file level 




$1C 


GET_DIR_ENTRY 


Gets information about entries in a 
directory 
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Device Functions 
$20 GET_DEV_NUM 

$21 GET-LAST-DEV 
$22 READ^BLOCK 

$23 WR1TE-BLOCK 

$24 FORMAT 
$25 ERASE 
$2C D-INFO 

Environment Functions 

$27 GET_NAME 

$28 GET_BOOT_VOL 

$29 QUIT 

$2A GET_VERSION 

Interrupt Control Functions 
$31 ALLOC-INTERRUPT 

$32 DE ALLOC-INTERRUPT 



Gets the device number for a device or 

volume 

Gets the last-accessed device number 

Reads a 512-byte block from a device into 

memory 

Writes 512 bytes from memory to a block 

device 

Formats a device in various DOS formats 

Erases a formatted device 

Converts a device number to its device 

name 



Gets the pathname of the active 

application 

Gets the volume name where PRODOS 

was launched 

Exits the current application 

Returns the version number of ProDOS 16 

Allocates an interrupt handler with 

ProDOS 

Deallocates an interrupt handler from 

ProDOS 



Note that the names given here are the official names used by 
Apple Computer. C programmers can use these names just as 
they are. To use them in assembler macros, just put an under- 
score in front (for instance, _ERASE). For TML Pascal pro- 
grammers, prefix each command with the letters P16 and 
leave out any underscores (for instance, P16GetBootVol). 






Did you notice that some function numbers appear to be miss- 
ing? This isn't a mistake. Apple Computer has intentionally placed 
"holes" in the ProDOS 16 command table for future enhancements 
and additions. 

Building a Parameter List 

Ivify PF8D0§ eall Fequire a parameter list in order to pa§§ infgp 

mation between ProDOS and your program. In machine language, 
the address of the parameter list follows the command number im- 
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mediately after the JSL SE100A8, In C and Pascal, the argument to 
each ProDOS 16 function is the address of the corresponding pa- 
rameter list. 

Values in a parameter list consist of the types listed in Table 
14-2. 

Table 14-2. Values in a Parameter List 



Type Sire 

Constant Word (2) 

Constant Long (4) 

Pointer Long (4) 



Sample Uses 

A flag, code number, bit field, reference number 

File offset, block number, and so on 

Address of a pathname string or storage buffer 



Note that unlike ProDOS 8, only word and long-word values 
are used in parameter lists in ProDOS 16. 

A long pointer to a pathname, such as a prefix, the name 
of a file, device, or volume, is a Pascal-style string: It begins 
with a count byte. All parameters that reference strings are 
long pointers to buffers. Never does a parameter in the list 
contain string data. 



The layout of a sample parameter list for the OPEN ($10) 
function is demonstrated in Table 14-3. 

Table 14-3. Sample Parameter List 

Size Offset Parameter Description 

Word 00-01 ref_num Reference number 

Long 02-05* pathname Long pointer to filename string 

Long 06-09 io_buffer Address of I/O buffer 

* You must provide information in this field before making the call to ProDOS. The other 
fields indicate parameters returned by ProDOS. These returned values are stored In the pa- 
rameter block when the call is complete. In order to make the OPEN call, all you need to do 
is supply the pathname pointer, the second parameter. After the call is made. [*roD05 fills in 
the ref_num and io_buffer fields. Offsets are always shown in hexadecimal. 

An example of a parameter list in use is demonstrated by this 
subroutine in assembly language. It makes the OPEN call and ref- 
erences the parameter list, OParms: 

DoOpen 



Okay 



_0PEN 
bec 


OParms 
Oiay 


;0pen the file 

;lf carry is clear, the rile Is open 


Jmp 


HandlsDIskErr 


;Handle the error 


rts 




:The program then does whatever 
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OParme 

Oref_rium ds 

Opathname do 

QlO—buf da 

Filename 



A NO? 
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;Parametar Hat tor the OPEN function 
a :ref_mim returned by ProDOS 

WFlleName" ;long pointer to the filename to open 

a. ;lo_buffer address returned by ProDOS 

str '/SAMPLE/FILE' ;Name of file to open 

This same routine in C could be written like this: 



OParms = { 0, 



"\p/SAMPLE/7ILE" 
NULL ,i 



/• faf_num '/ 
/■ pathname 7 
/• lo_buf 7 



DoOpen( ) 

{ 

0PEN( fcOParms ); 
ir ( _tooiErr ) 
HandleDlekErr; 



} 



And, in IML Pascal, an equivalent procedure would be 



PROCEDURE DoOpen; 

VAR OParms: PieParamBlk; 
FlleNama: String; 

BEGIN 

FlteName := '/SAMPLE/FILE'; 
0Parms.pathname2 : = ^PUeKame; 
P160pen( OParms >; 
IF IOBesult > THEN 
HandleDlskErr; 
END; 

Using the parameter table for the CLOSE function, shown in 
the next section, see if you can figure out how to close the file 
opened above by including just a single function call, It's easier 
than you might think. 

ProDOS 16 Parameter Tables 

The following tables describe the parameter lists for every ProDOS 
16 call; 



If you're programming in a high-level language, check your 
compiler's manuals or support files for the appropriate names 
of each field in a parameter list record. 
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Table 14-4. Parameter Lists lor Every ProDOS Call 




SOI CREATE 






Offset Parameter 
Long 00-03* pathname 
Word 04-05* access 
Word 06-07* file-type 
Long 08-OB" aux_type 
Word 0C-0D" storage-type 
Word 0E-0F* create„date 

Word 10-11* create_time 


Explanation 

Address of pathname to create 

Access bits (that is, read, write, destroy) 

File type code number ($00-$FF) 

Auxiliary filetype code ($Q000-$FFFF) 

Storage classifier ($01-$0D) 

Date when file was created (usually 

$0000) 

Time when file was created (usually 

$0000) 




$02 DESTROY 






Size Offset Parameter 
Long 00-03* pathname 


Explanation 

Address of pathname to delete 




$04 CHANGE-PATH 






Size Offset Parameter Explanation 

Long 00-03* pathname Pathname to rename or move 

1 ong 04-07* new—pathname New pathname or location 




$05 SET_FILE_INFO 






Size Offset Parameter 
Long 00-03* pathname 


Explanation 

Address of pathname to get information 




Word 04-05* access 
Word 06-07* file_type 
Long 08-OB* aux_type 

Word 0C-0D* unused 
Word 0E-0F* create_date 
Word 10-11* create_time 
Word 12-13* mod-date 
Word 14-15* mod_time 


on 

Access bits 

Filetype code number 

Auxiliary type (or total—blocks if D1R 

file) 

Date when file was created 
Time when file was created 
Date when file was modified 
Time when file was modified 




$06 GET-FILE-INFO 






Size Offset Parameter 
Long 00-03* pathname 


Explanation 

Address of pathname to get information 




Word 04-05 access 
Word 06-07 file-type 
Long 08-OB aux_type 


on 

Access bits 

Filetype code number 

Auxiliary type (or total—blocks if DIR 

file) 
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Word 0C-0D 


storage— type 


Storage classifier 


Word 0E-0F 


create— date 


Date when file was created 


Word 10-11 


create— time 


Time when file was created 


Word 12-13 


mod—date 


Date when file was modified 


Word 14-15 


mod—time 


Time when file was modified 


Long 16-19 


blocks_used 


Blocks in used by this file (or volume) 


$08 VOLUME 






Size Offset 


Parameter 


Explanation 


Long 00-03* 


dev_ name 


Name of device to get information on 


Long 04-07 


vol— name 


Address of buffer to store volume name 


Long 08-OB 


total— blocks 


Volume's total capacity in 512-byte 

blocks 


Long 0C-OF 


free—blocks 


Number of unused blocks on the 
volume 


Word 10-11 


file_ sys_ id 


Filesystem ID (identifies disk format) 


$09 SET-PREFIX 




Size Offset 


Parameter 


Explanation 


Word 00-01* 


prefix— num 


Number of the prefix to set 
($0000-$0007) 


Long 02-05* 


prefix 


Address of prefix string 


$0A GET-PREFIX 




Size Offset 


Parameter 


Explanation 


Word 00-01* 


prefix— num 


Number of the prefix to get 
($0000-$0007) 


Long 02-05* 


prefix 


Address of returned prefix storage 
buffer 


$0B CLEAR_BACKUP_BIT 




Size Offset 


Parameter 


Explanation 


Long 00-03* 


pathname 


Address of pathname to have its bit 
cleared 


$10 OPEN 






Size Offset 


Parameter 


Explanation 


Word 00-01 


re f_ num 


Opened file's reference number 


Long 02-05* 


pathname 


Address of pathname to open 


Long 06-09 


io_ buf 


Address of io_buffer for this file 


$11 NEWLINE 






Size Offset 


Parameter 


Explanation 


Word 00-01* 


ref_num 


Opened file's reference number 


Word 02-03* 


enable— mask 


Logical AND bitmask used against each 

byte 


340 











ProDOS 


Word 04-05* 


newtine_char 


The newline character (in lower byte) 


$12 READ 






Size Offset 


Parameter 


Explanation 


Word 00-01* 


ref_ num 


Opened file's reference number 


Long 02-05* 


data_buffer 


Address of buffer where data is read 
into 


Long 06-09* 


request_count 


Number of bytes to read from file 


Long OA-0D 


transfer_count 


Actual number of bytes read from file 


$13 WRITE 






Size Offset 


Parameter 


Explanation 


Word 00-01* 


rei_num 


Opened file's reference number 


Long 02-05* 


data—buffer 


Address of data to write into the file 


Long 06-09* 


request_count 


Number of byles to write 


Long 0A-0D 


transfer— count 


Actual number of bytes written 


S14 CLOSE 






Size Offset 


Parameter 


Explanation 


Word 00-01* 


ref_num 


Opened file's reference number 



515 FLUSH 

Size Offset Parameter 

Word 00-01* ref_num 

516 SET_MARK 

Size Offset Parameter 

Word 00-01* ref_num 

Long 02-05* position 



$17 GET_MARK 


Size Offset 


Parameter 


Word 00-01* 


ref_num 


Long 02-05 


position 


$18 SET_EOF 




Sire Offset 


Parameter 


Word 00-01* 


ref_ num 


Long 02-05* 


eof 


$19 GET-EOF 




Size Offset 


Parameter 


Word 00-01* 


ref_num 


Long 02-05 


eof 



Explanation 

Opened file's reference number 

Explanation 

Opened file's reference number 
How far into the file to seek 



Explanation 

Opened file's reference number 
Current position in file 

Explanation 

Opened file's reference number 
End-of-file position (file size in bytes) 

Explanation 

Opened file's reference number 

End-of-file position (file size in bytes) 






$1A SET-LEVEL 

Size Offset Parameter 
Word 00-01* level 

SIB GET_LEVEL 

Size Offset Parameter 
Word 00-01 level 



$1C GET_DIR_ENTRY 


Size 


Offset 


Parameter 


Word 


00-01* 


ref_num 


Word 


02-03* 


reserved 


Word 


04-05* 


base 


Word 


06-07* 


displacement 


Long 


08-0B* 


filename 


Word 


0C-0D 


entry_num 


Word 


0E-0F 


file_type 


Long 


10-13 


eof 


Long 


14-17 


blocks— used 


Word 


18-19 


create_date 


Word 


1A-1B 


create_time 


Word 


1C-1D 


mod_date 


Word 


1E-1F 


mod—time 


Word 


20-21 


access 


Long 


21-24 


auK_ type 


Word 


25-26 


file— sys—id 



$20 GET_DEV_NUM 

Size Offset Parameter 
Long 00-03* dev_name 
Word 04-05 dev_ num 

$21 GET_LAST_DEV 

Size Offset Parameter 
Word 00-01 dev_num 

$22 READ-BLOCK 
Size Offset Parameter 
Word 00-01* dev_num 
Long 02-05* data_buffer 
Long 06-09* block_num 
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Explanation 

New system file level for opens and 

closes 



Explanation 

Current system file level 

Explanation 

Open DIR file's reference number 

Must be set to $0000 

Positive or negative code for 

displacement 

Entry displacement from current entry 

Address of filename buffer 

Entry number 

FUetype of the returned entry 

End-of-file position (file size in bytes) 

Number of blocks in use by this entry 

Date file was created 

Time file was created 

Date file was modified 

Time file was modified 

Access bits 

Auxiliary filetype 

Filesystem ID 

Explanation 

Address of device name string 

The device number of the named device 



Explanation 

Last accessed device number 



Explanation 

Device number to read from 
Address of 512-byte data buffer 
Block number to read 
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$23 WRITE-BLOCK 




Size Offset Parameter 


Explanation 


Word 00-01* dev_num 


Device number to write to 


Long 02-05* data_buffer 


Address of 512-byte data buffer 


Long 06-09* block_num 


Block number to write 


$24 FORMAT 




Size Offset Parameter 


Explanation 


Long 00-03* dev_name 


Address of device name to format 


Long 04-07* voLname 


Address of the device's new volume 




name 


Word 08-09* fi!e_sys_id 


Filesystem ID code 


$25 ERASE 




Sue Offset Parameter 


Explanation 


Long 00-03* dev_name 


Address of device name to erase 


Long 04-07* voLname 


Address of the device's new volume 




name 


Word 08-09* file_sys_id 


Filesystem ID code 


$27 GET_NAME 




Size Offset Parameter 


Explanation 


Long 00-03* data_buffer 


Address of application's pathname 




buffer 


$28 GET_BOOT_VOL 




Size Offset Parameter 


Explanation 


Long 00-03* data-buffer 


Address of boot volume's name buffer 


$29 QUIT 




Size Offset Parameter 


Explanation 


Long 00-03* pathname 


Address of pathname to quit to 


Word 04-05* nags 


Return and Restart flags in bits 15 & 14 


$2A GET_VERSION 




Size Offset Parameter 


Explanation 


Word 00-01 version 


Major and minor release versions of 




ProDOS 


$2C D_INFO 




Size Offset Parameter 


Explanation 


Word 00-01* dev_num 


Device number to convert 


Long 02-05* dev_name 


Address of 3 2 -byte device name buffer 
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$31 ALLOC-INTERRUPT 
Size Offset Parameter 
Word 00-01 int_num 
Long 02-05* inLcode 

$32 DEALLOC-INTERRUPT 

Size Offset Parameter 
Word 00-01* int_num 



Explanation 

Interrupt reference number 

Address of interrupt handling routine 



Explanation 

Interrupt reference number 

• You musl provide information in this field before making the call to ProDOS. The other 
fields indicate parameters retained by ProDOS. These relumed values arc stored in the pa- 
rameter block when, the call is complete. In order to make the OPEN call, all you need to do 
is supply the pathname pointer, the second parameter. After the call is made. ProDOS will 
fill In the ref_num and io_buffer fields. Offsets are always shown in hexadecimal. 

Standard File Operations 

Tool set 23 ($17), the Standard File Operations tool set, contains a 
handful of functions that make file selection easier for both the 
programmer and the user of the program. These tools work in the 
super-hi-res graphics displays in 320 or 640 modes and present the 
user with a dialog box containing a list of selectable filenames. 

Figure 14-1. A Standard File Operations Dialog Box 



Fix which file: 

■S) /H/flpw/Fixer/ 




D Fixdisk.C 


u 


D Fixer. H 

D Fixevent.C 

D Fixmain.C 

CD Fixob j 

D Fixtools.C 

D Makefile 


A 



Disk 



Open 



c 



Close 



J 



C Cancel ] 



In addition to the standard housekeeping calls (StartUp, Status, 
and so on) the Standard File Operations tool set provides the func- 
tions shown in Table 14-5. 
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Table 14-5. Functions Provided by Standard File Operations Tool Set 

ID Function 

$0917 SFGetFile 

$0A17 SFPutFile 

SOB 17 SFPCetFile 

$0C17 SFPPutFile 

$0D17 SFAllCaps 

Note thai these 1 are toolbox (alls, not ProDOS 16 commands, 



Description 

Allows the user to select a file to open 

Lets the user choose a file to be saved 

Same as SFGetFile, except uses a custom dialog 

Same as SFPutFile, except uses a custom dialog 

Chooses uppercase or mixed case filename displays 



SFGetFile 

Use SFGetFile when your program prompts the user to select a file 
to open. Some examples follow. 
In machine language: 



pusbword 


•WbereX 


left coordinate or dialog box 


puahword 


'WhereY 


top coordinate of dialog box 


pushlong 


•Prompt 


address of prompt string 


pushlong 


•FilterProc 


address of filter procedure 


pushlong 


•TypeLlat 


address of valid flletypes list 


pushlong 


•Reply 


address of reply record 


—SFGetFile 







In C: 
SFOetFlle( wherex, wbereY, "\pPrompt", fefllterProc, fctypeLlat, *reply ); 

In Pascal: 
SFGetFileC WbereX. WbereY. 'Prompt', PFllterProc, tfTypeLlat, Reply ); 

The WhereX and Where Y values specify the position on the 
screen where the dialog box will be placed. 

The Prompt string is a Pascal string which is displayed at the 
top of the dialog box. This should indicate to the user the purpose 
of the dialog box by giving a one-line instruction, such as Select a 
pen:. 

Your program may not want the user to be able to select cer- 
tain files. So you can write your own filter procedure to determine 
how files are to be displayed in the list. If the address of FilterProc 
is 0, no filter procedure is called. Otherwise, your filter routine is 
called for every entry to be placed into the scrolling filename list. 
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FilterProc is invoked in the following manner by the Standard File 

tool set: 



pushword *0 

pushlong 'CurrentEntry 

jsl YourPllwrProc 

pull word ReaultCode 



;result space that you will fill in 
;tbe addraaa of a directory entry 
;then your filtering routine la called 
;pull reault code 



As shown, your filter routine must access the two arguments 
on the stack in order to specify how the current directory entry 
should be placed in the list. Note that when your filter routine is 
called, the stack will contain a long return address, followed by a 
long pointer to a directory entry structure and a word of result 
space. 

The result that your filter routine returns is one of three 
values: 

Value Meaning 

Do not place the entry into the dialog window 

1 Place it in the window, but make it dimmed and not selectable 

2 Place it in the window and allow it to be selected 

Since the filter procedure must access each file's directory 
record, you need to know the structure of this 39-byte buffer. This 
structure is shown in Table 14-6. 

Table 14-6. Structure of Directory Record 

Directory Entry Description 

Storage classifier (upper nibble) 

Filename length (lower nibble) 

String of characters for filename 

Filetype code ($00-$FF) 

Pointer to index block 

Number of blocks in use by this entry 

End-ofTile position (file's size in bytes) 

Date file was created 

Time file was created 

Version of ProDOS that created this file 

Oldest version of ProDOS that can use this file 

Access bits 

Auviliary filetype 

Date file was last modified 

Time file was last modified 

Block number of this file's parent directory 
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Offset 


Field 


00 


storage_type 




name—length 


01-0F 


file— name 


10 


file_type 


11-12 


key_ pointer 


13-14 


blocks— used 


15-17 


eof 


18-19 


create_date 


1A-1B 


create_time 


1C 


version 


ID 


min_verSion 


IE 


access 


1F-20 


aux_ type 


21-22 


mod—date 


23-24 


mod—time 


25-26 


header— pointer 
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A few fields in this record contain byte values, so you might 
have to put the processor in eight-bit mode for some operations. 

The most straightforward way to filter out a directory entry is 
done as shown in the following routine. It checks the filetype of 
the current entry to see how the entry should be displayed: 

;dlreot page storage for a long pointer 

;Pull RTL address off stack 
;sat up a long pointer to the entry record 
;unload result space from stack for now 
;lndei Into filetype field of entry record 
;grab the filetype byte (and next byte) 
;make only the filetype byte significant 
;X = 0: do not display (assume BAD) 
;ls it a BAD block file? 
:yea 

;X = 1: display as dimmed (not selectable) 

.Is It a DIR file? 

lyes 

;X = 2: display and make selectable 
;puBh filter code on stack 
:put return address back on stack 
;and return to It 

iStorage for return address 

Once control returns to SFGetFile, it pulls the filter code off 

the stack and knows how to handle the entry. 

Another way to filter entries is to provide a list of acceptable 
filetypes by pointing to a TypeList table. Only the file entries 
which have types listed in the table will be placed into the dialog 
box. A TypeList begins with a count byte (not a word) followed by 
a string of byte values indicating valid filetypes. For example: 

TypeList dc U'4','04,0B.1A.B0' '.Four document types 

If you specify a null address for a TypeList, or the list begins 
with a count byte of 0, this added filtering method is ignored. But, 
if you specify both a FilterProc and a TypeList, your filter proce- 
dure will be called only for the entries that satisfy the file types in 
the TypeList. 

The final argument to the SFGetFile tool call is the address of 
a Reply record in the format shown in Table 4-6. 
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DtrBntry 


equ 


♦PC 


MyFllter 


pulllong 


Return 




pulllong 


DlrEntry 




pla 






Idy 


•110 




Ida 


[DlrBntry].y 




and 


*tCT 




Idx 


•loo 




omp 


••oi 




1*q 


Done 




tax 






cmp 


*$0D 




beq 


Done 




Ins 




Done 


phx 






puahlong 


Return 




it! 




Return 


ds 


4 
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Table 4-6. Formal of the Reply Record 

Offset Field Name Reply Record Description 

$00-01 good True if Open clicked; false if Cancel clicked 

$02-03 file—type Filetype code of the file selected 

$04-05 aux_file_type Auxiliary filetype code 

S06-15 filename Name selected from name list (16 bytes) 

$16-96 fulL-pathname Full pathname to file (129 bytes) 

This record is filled in with values by SFGetFile whenever the 
user clicks the Open or Cancel buttons. 

Your program will know whether it should continue with file 
operations by examining the good field of the Reply record. If it 
contains a false (0) value, the program knows that the user clicked 
Cancel. Any nonzero value means the Open button was clicked. 

SFGetFile also returns the filetype and aux_file_type codes for 
the file selected. This information might be useful to your program. 

The filename and full-pathname fields are Pascal-style strings. 
The 15-character filename is the name of the file selected as it was 
shown in the scrollable list (mixed case and all). The fulL-pathname 
is a fully qualified pathname to the file selected. 

After a file is chosen, the current ProD05 prefix is set to the 
subdirectory (or, the folder) that contains the selected file. 

SFPutFile 

Use the SFPutFiie function to allow the user to select a file when 
saving information to disk. If the user selects a file that already ex- 
ists. SFPutFile will bring up a second dialog box on its own to ask 
the user whether it's okay to overwrite the existing file. 
In machine language: 



left edge of dialog 

;top edge 

.address of prompt string 

address of original filename 

maximum number of characters In name 

.address of reply record 



puehword 'WhereX 

pushword *WhereY 

pushlong 'Prompt 

puahlong 'OrlgName 

pushword 'MaxLen 

pushlong 'Reply 

In C: 

SFPutFIle( whereX, uhereY. "\pPrompt". AorlgName. maxLen, S-reply ): 

In Pascal: 

SFPutFlle( WhereX. WnereY, Prompt', POrlgName. MaxLen. Reply ); 
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The WhereX and WhereY values specify the position on the 
screen where the dialog box will be placed. 

The Prompt string is a Pascal string and should provide a mes- 
sage, such as Save document to:, giving the user an idea of the oper- 
ation at hand. 

OrigName is the address of a Pascal string to be placed into 
the EditLine item in the SFPutFile dialog. OrigName normally 
points to the filename returned by SFGetFile when the file was fust 
opened. 

MaxLen indicates the number of characters that can be entered 
in the EditLine item. This is usually 15 since the current implemen- 
tation of ProDOS limits filenames to 15 characters. 

The last argument is the address of the Reply record as de- 
scribed in the SFGetFile section. Both SFGetFile and SFPutFile use 
the same Reply record format. 

SFAUCaps 

Normally filenames are shown in mixed case in the scrolling list of 
names in a Standard File dialog box, but if you prefer all upper- 
case, use the SFAUCaps function with a Boolean value of true (any 
nonzero value}. A false value (0) indicates mixed case. 
In machine language: 

pushword *1 :true: show names In all uppercase 
_SFAllCapB 

In C and Pascal: 

SFAHCaps( TRUE ); 

A Nonredundant Example 

Because ProDOS calls occupy a relatively small portion of the sam- 
ple program for this chapter, things will be handled a bit differ- 
ently. Rather than providing three huge programs in machine 
language, C, and Pascal, only one program is presented in its en- 
tirety. C was chosen for the job because it is midway between the 
low-level control of machine language and the high-level ease of 
Pascal. The section containing the ProDOS calls is provided in both 
machine language and Pascal, however. 

The program listed below, CRC.C, is a 320-mode desktop pro- 
gram that calculates a cyclic redundancy checksum on the contents 
of a disk file. Unlike most of the other programs in this book. 
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CRC.C uses no pull-down menus. Instead, the program is centered 
around the Standard File Operation's SFGetFile dialog box on the 
desktop. The user selects a file and clicks the Open button to begin 
the CRC calculation. To quit the program, the user simply clicks on 
the Cancel button. Putting a pull-down menu into a program like 
this would introduce an unnecessary step, so menus are left out. 



What in the world is a CRC? A CRC is a calculation on a piece 
of data that results in a unique 16-bit value, It's used mainly 
in data communications protocols to ensure the correct transfer 
of a file over less-than-pristine telephone connections. For 
everyday purposes, it can be used to quickly compare two files 
that are supposed to be identical to see if they are different. 



CRC.C 

This program demonstrates how to use the SFGetFile function to 
allow the user to select a file from disk. It will open the selected 
file, read through it, trap the famous "end-of-file" error, and close 
the file; a typical file-handling procedure. Note also how this pro- 
gram can easily be changed to run in 640 mode just by modifying 
two definitions near the top of the program. 

Program 14-1. CRC.C 



CRC.C 

Cyclic Redundance Ch eel sum Calculator 

Written bv Morgan Davis 



•include types. h 
•include '.locator. H- 
nine luce memory. h 
■ include •aisctool.h 
■incluae .Quickdran.h 
• include Qdaua .n 
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•include 'event .h ■ 










•include ninOOH.h' 










* include •» meedit. 


II ' 








• include control .h 


> 








■ include -dtelog.h' 










• include stdfile.h." 








•include 'intmatn.h 










■include vpi-odo*.n> 










•define node 


320 




t* Screen node 


<320 or 6401 •/ 


•define WasterSCB 


»ode320 




/• HaxWidtn noc 


e 1320 or 640) •/ 


•define Center 


I (Mode - 


1J / 2> /» Center pixel 


column *l 


•define BovUidtn 


240 




/• Dialog box size ■!• location •/ 


•define Bom Height 


70 








■define BoxX 


{Center 


(BoxWidth 1 2m 




•define BoxY 


40 








•def me Buf ferSize 


204B 


/■» 


Sue of file input Buffer »/ 


GrefPortPtr DialogPorti 


/* 


Dialog port »/ 




hHiTwkRtc EventRec; 


/• 


Event Record Structure *l 


SFReplvFcec Reply! 




/• 


Standard File Record Structure •/ 


OpenRec Of arms \ 




/« 


Open File parameter 


1 ist -I 


FilelQRec RFarms: 




/* 


Read File parameter 


list -1 


OuitRec QParms 


- ( OL, 


)« /• 


Ouit parameter 1 ist 


«/ 


Word User ID, 




1* 


Our User Itl ■/ 




nemJB, 




/« 


neaiory Management ID */ 


CfiCs 




1* 


The CRC •/ 
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PUinlnr 1/1 .^ — 


■— — ^— t_,napi<3T m 


Word Tool ktttl » ( 6, 


]«, tf, /« Window Manager •! 


16, C '* 0*100 Control Manager •/ 


IS, 0, /* QuickDraw II flux •■' 


20, 0, /• 0x100 LineEdit *l 


21, 0, rf Dialog Manager »/ 


23, /• 0*100 Standard File •/ 


), /» 0>.300 QuickDraw II »/ 


/» 0x100 Event Manager */ 


/a ■■■■■ total direct page space i* ••• •' 


• define DPageSue 0*7001. 


char »DP8ase ! t* Direct Page base pointer •/ 


ItemTemplate OKIten ■ t <* , 


BoxHeight-22, BoxNidth-68, 0, 0, 


but ton I ten, 


"\p OK ", 


0, 0, NULL 


); 


Dial ogTe«pl ate CRCBox = t 


Boxl", BoxX, Box r«BoxHeight , BoxX-*BoxWidth, 


1 . 

NULL, 


MKItt*. 


NULL 




1 



PwDOS - 



Handle Toolbox Errors 



ErrChk 1 1 
f 

If l_toolErrl Sy^FaUnqri tool Err, NULL); 

) 

« Manage Direct Page Buffers * 



/« Check (or error. die li so •■ 



cnar »GetI<Piovtes> 

Word bytes ; 

t 

char »01dDF = Df-Base; 
t'FBase t= bytes: 
return <0I dDF > ; 



/• Update base level pointer tr 
it Return old W'base pointer •* 



/* « 

Start Lto Tool* • 

StartUpToolsl) 
( 

UOfd GetDPO; 



" Force words from GetDP */ 



TLStartUp ( I ; 

h>*ID * (UserlD » HMStartUp C> > I 25&| 



ErrChk. 1 1 i 
ErrChk ( ) | 
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rlTStartUpl) : ErrChM); 

DFBase = MNewHandle (DPageSize , nemlD,. OkcOOS, NULL) ) I ErrChk O i 

uI)StartuotGetDP(Ciit300>, HasterSCB, 0, UserlD) t ErrChk « i ; 

EIStartUpiGetDPIUKlOOr , 0x14, 0, Node, 0, 200, UserlD); ErrChk (t i 

SetForeColor(y) ; 
SetBackColorf.il i 
HoveTcl20.:'"' : 

DrawCStringl "One moment.,.")! 
lnitCursor (I s 



LoadToo l s i Tool i st i ; 
OOAuxStarlUpl) | 
HindSt*rtUplli«erlD) | 
CtlStartUpClJsertD, GetDFMOxlQO) ) I 
LESt*rtUplU»erly, 6etDP (Ox 100) ) | 
DialoaStartyplUserttl) | 
SFSt«rtUp<U»erID, GetDPlOx 100) ) i 

D»sktop(5, 0x40000030)? 



ErrChk () ; 
ErrChk < ) s 

ErrChk [) i 
ErrChk ( ) ; 
ErrChk ! > j 
ErrChk C > ; 
ErrChk ( ) i 






• Calculate CRC on a Buffer 



/» A CRC is the result of a mathematical operation based on the 

* coefficients of a polynomial «hen multiplied by «'16 then divided by 

* the senerator polynomial IX' 14 * XM2 * X"5 ♦ 1) using modulo two 
» anthaetic. That's okay, 1 don't understand it either. 

* / 
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CalcCRC (ptr, count) 
char "ptr; 

Word count i 

{ 

Word k : 



ProDOS 



/• Pointer to start of data butter */ 
I* Number of bvtes to scan through */ 



do I 



ORC = »ptr*-» • 8: 
lor (x = Si x ; — » ) 
M 4 CRC h 0x6000) 



/• XOR hi-bvte of CRC «/ data »/ 
/• Then, for 9 bit shifts... •/ 
'• Test hi order bit of CRC */ 



CRC = CRC « 1 0x|Q2l; /• if set. shift i XOR w/*l021 »/ 
else 

CRC «» I| /• Else, just shift left once.t/ 

) while ( — count); I* Do this for all bytes »/ 



* Bet CRC on the File » 
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OPEN (iOParmsH 
Error ■ tool Err; 
if I -Error) C 

RRarms.f ileRefNum ■ OP*r«is,oeenRef Nu* ; 
ftParms.dat aBuffer ■ Buffer; 
RFarms.reotiestCaunt = BufferSize; 
do < 

READ t*RParm«l t 
Error = _too)Erri 
t f < Error > C 

EOF « TRUE: 

if (Error =- eofEncOcifitered I 
Error ■ 0; 
) el se 

CalcCRC I Suffer, RFarms.transferCount i i 
) while ('EOF)! 



f Doen the file *' 



ft If no error ... if 



■» ...read some oata •/ 

I • If error. . . */ 

f* flag EOF •/ 

H EOF isn't fatal ... « 

/ • . . -so :#ro error • I 



CLOSE (fcOParms.1 : 
return I Error) : 



/• Close the file »/ 

/* And return error code ♦' 



OetCRC ipatnnane) 

char •pathname; /* Fainter to full pathname *i 

C 

Word Error; 

fcoolean EOF ■ FALSE; 

char Ruf ferCBuf I erSuel; 

OParas.openPathname ■ pathname! 



* Show CRC in Modal Dialog ♦ 



char »CF£str - i \ 

cfiM" »fcrrorrtsg = "FroDOS Error' Code 

WorO Error j 



Wait Cursor i i s 
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Pmnnc 




^^^^^^^^^^^^^^^^^^^^^^ rrou\Ji> ^— ^— — — ^— ^^— ^^ 




foialcgfort = GetNewriodal Dial oqftCRCBo:. / ; .* Create modal dialog •/ 






SetPort tDialogFort i ; 






nqv»Toao,20i ; 






DrawCStringC'Gettinj CRC on ')• /• Print a prompt •/ 






DrawString (Reply,* il enamel j 






DrawCStrin9( M , . .") | 






nov*To<Bo><Uidth/2 - 2h, 36) : 






CftC - 0: ... imt CftC at zero #/ 






Error ■ GetCRCIRepl y.+ul (Pathname) ; /« Get DftC on true file •' 






if (Error) ( /* h in error occurred 1 ... •/ 






rtoveToU0,36> s /. ... print a message •/ 






DrawCStrin9(ErrorHs9( ; 






SysBeep ( ) : 






CRC ■ Error i 
) 






!flt2HexiCRC 4 CRCstr * i, *i ; ,. Mate CRC printaol* #/ 






LirBwC&tring<CRCstr ' : /• Inen print it »/ 






In I tCuraor | 






nodal Dialog -NULL' ; /• wait for 01 Butter. •/ 






CI oseDialag'C'i alogPort; s I* Close the dialog • 






. , 






» "jnutdown Toolsets • 










1 


■■ 
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^Finutt'owni i : 
LtinutLiowm i : 
Ct I Shutdown 1 1 1 

Ni.n03hwU>0»> 
EIIShlltDQMnl) | 

DDAuk Shut Down I < : 
DDStaJtDownl) i 
hT5nutDown ( j : 
Dispose"! I • MemlL'i : 

nHShut ['own 'User I i> • : 
TLSfiutliowni ' : 



/♦ Display a standard Fll« CloeraUons "Get" Dialog and wait *ot * 
• »ile to B» selected. If Cancel is selected, tne program auits. 



Start UpToolsl) i 
do ( 

SfGetFileiCenter-13<.., 35. "\pCalculate CRC orn", PL, OL , *Reply>; 
if iR«o1v.9oodf /• If Oo«" clicked ... *V 

SfiowCRCOt /• ... do the CRC « 

) while (Reptv.joodi ! 
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atvjtl'OwrjTool S I I i 

QUIT (MVarnsi: 



CRC.ASM 

To complete the machine language version of this program, simply 
steal parts of the MODEL.ASM and other examples from this book 
which correspond to most of the routines in CRC.C. Program 14-2 
and 14-3 are two new subroutines, GetCRC and CalcCRC in ma- 
chine language. 

Program 14-2. Calculate CRC on a Buffer 



■» Calculate C&L on a fruffer » 



i OV Hi'' 

NKt&vte short t> 

Ida Suffer, 1 

iny 

eor CRC* J 

st a CRC* I 

lonqm 

10' »8 

Shut a 5 l CRC 

Bcc net 

I da CRC 

eor 1*102,1 

st a CSC 



Next fl§ 



bn« Sh 1 1 1 



unit index into buffer 

;go to 9-bit accumulator 

sgraO a character 

iDunp inde:-. 

:U.: man-order byte of CSC 

;bad to 16-bit accumulator 

iimt shi + t counter 

i shift CRC left once always 

;i» bit 15 Has clear, =.» 10 the XOF. 

:*0R CRC with 11021 



:do this 8 times 
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dec K ♦ btNu* 

One NKtBvte 



irtore bvtes to do" 
;yes if count not ;ero 



CRC ds 2 ihere's the CRC word 

Program 14-3. Get CRC on the File 



a Gat CRC on the Fl l« • 



Set CRC _0PE« 0P*r»* 
bca StopErr 



•oveword 0re4 ,Rref 


RdLoop _READ 


RParins 


DCS 


Chi Err 


JW 


■ 


bra 


RdLooD 


CM Err c»D 


NMC 


one 


StopErr 


Ida 


NO 


StooErr sta 


Error 


CLOSE 


OParinB 


rts 





;0pen the file 

sstop if error occurred 

;Cqby reference nuirber 

:Read data from file into Buffer 

terry occurred -- cned tor EOf 

jno error • so update Cfvt 

land qo eae»- to read more until EOF 

tend of file ■ 

;no, »o return it 

iflat no error — EOF isn't fatal 
isave error return code 
[close the file 
jand return 

! error c ode I oc at i on 
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Buffer as BufferSire iflats buH«r 






OPanns ANOF' ;OPEN Parameter List 






Qre» ds 2 sopen -f 1 1 e reference numoer 






dc i4 oathname ;pointer to pathname 






ds 4 : address of 1/0 Buffer 






ftf-arms ANOP ;READ Parameter List 






Rref ds 2 {reference number for reading 






dc i»'Buffer' joointer to data buffer 






l*+#rSl2e iSize of butter 






.:ierllum ds * ,-rer count 






CRC.PAS 






The GetCRC and CalcCRC routines in TML Pascal are shown in 






Program 14-4. 






Program 14-4. Calculate CRC on a Buffer 






• Calculate CRC on a Buffer • 






( Note that the global variable CRC has range 0' 10940. .tFFf F ) 






PROCEDlttE CalcCRC IStlfPtri Ptr; count: Integer! : 






van xi Integers 






Lata: *0000. .*FFFFj 






BEGIN 






REPEAT 






Data :■ huf Ptr' 5 






FOR » ;= I TO 8 DO 




1 


Data : = BitSL (Data) ; 
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CRC l" BltXOR (CRC, Data)! 

bufPtr := Pointer (Lonfllnt (bufPtr) ♦ Hi 

FOR v :- I TO 9 DO 

IF CRC > »7FFF THEN 

CRC i= BltXOR (BitSL <CRC) , flOSI) 
ELSE 

CRC : = BitSL (CRCI i 
Dec (count I : 
UNTIL (count - 01 t 



EMU: 



• Get CRC on the File » 

FUNCTION &etCKC ipathname: StrmgPtrJ : Integer; 
VAR Error : 1 nteger : 

EOF: Boolean; 

Buffer: Faded Array CO. .Buf ferSizel of Bvte: 

(Warms: PlftPararaBH- ; 

RParas: PlbParamBH : 
BEGIN 

EOF i= FALSE : 

OParms .Pathname; :■ patnnaee; 

PI60pen (OPsrifisj j 

Error :* lOResultj 

IF Error = THEN BEGIN 

PFarms.ref Num :* QParms.refNum; 
fiFarms.dataBuff er :- f&uffarCOl; 

i-farM .requestCount != BufferSne! 
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REFEftT 

Pt&Reag lRF.armsi ; 
Error := IDResul t t 
IF Error .■ THEN 
BEGIN 

EOF := I RUES 

IF Error - J4C THEN Error := Ol 
END 
ELbt 

CalcCAC i«funfi-[i.i], KF'arat . traf\s« erCoyftfcf : 
LINTIL EOF; 
END; 

F-IolIos* lOf'armsn 
GetCPC :* Error; 



Disk Errors 

Table 14-7 is a complete list of error codes that can be returned by 
the ProDOS 16 operating system. {See the "Checking for Errors" 
section in this chapter for details on how to detect and handle 
errors). 

Table 14-7. ProDOS 16 Error Codes 



Number Meaning 

£00 No error 

$01 Invalid call number 

$07 ProDOS is busy 

$10 Device not found 

$11 Invalid device request 

$25 Interrupt vector table full 

$27 I/O error 

$28 No device connected 

$2B Disk is write-protected 

$2E Disk switched, files open 

$2F Device not online 

S30-S3F Device-specific errors 
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Number 


Meaning 


$40 


Invalid Pathname 


$42 


File control block table full 


$43 


Invalid reference number 


$44 


Patb not found 


$45 


Volume not found 


$46 


File not found 


$47 


Duplicate pathname 


S4* 


Volume full 


$49 


Volume directory full 


$4A 


Version error 


$4B 


Unsupported storage type 


$4C 


EOF encountered, out of data 


$4D 


Position out of range 


$4E 


Access not permitted 


$50 


File is open 


$51 


Directory structure damaged 


$52 


Unsupported volume type 


$53 


Invalid parameter 


$54 


Out of memory 


$55 


Volume control block full 


$57 


Duplicate volume 


$58 


Not a block device 


$59 


Invalid file level 


$5A 


Block number out of range 


$5B 


Illegal pathname change 


$5C 


Not an executable file 


$5D 


File system not available 


$5E 


Cannot deallocate /RAM 


$5F 


Return stack overflow 


$60 


Data unavailable 



Chapter Summary 

The following functions are part of the Standard File Operations 
tool set, which is presented in this chapter: 

Function: $0117 

Name: SFBootlnit 

Initialize the Standard File tool set environment 

Push: Nothing 

Pull: Nothing 

Errors: None 

Comments: Applications do not make this call. 
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Function: $0217 
Name: SFStartup 

Starts up the Standard File Operations tool set 
Push: User FD (W); Direct Page (W) 

Full- Nething 

Errors: None 
Comments: Call this before using Standard File functions. 

Function: $0317 

Name: SFShutdown 

Shuts down the Standard File tool set and frees some 
memory 
Push: Nothing 
Pull: Nothing 
Errors: None 
Comments: Call this when your application is done using Standard File 
Operations. 

Function: $0417 
Name: SFVersion 

Get the current version of the Standard File tool set 
Push: Result Space (W) 
Pull: Version number (W) 
Errors: None 

Function: $0517 
Name: SFReset 

Reset the Standard File Operations tool set 
Push: Nothing 

Pull; Nothing 
Errors: None 

Function: $0617 

Name: SFStatus 

Determine if the Standard File Operations tool set is active 

Push: Result Space (W) 

Pull: Active flag (W) 

Errors: None 

Comments: The flag is if false and nonzero if true. 

Function: $0917 
Name: SFGetFile 

Lets the user choose a specific file from a dialog box 
Push: X position of dialog box (W); Y position of dialog box (W); 
Pointer to dialog box title string (L); Pointer to filtering sub- 
routine (L); Pointer to list of valid file types (L); Pointer to re- 
turned pathname record structure (L) 
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Pull: Nothing 
Errors: None 
Comments: Title string starts with a count byte. Calling of the filtering 
routine can be inhibited by using $00000000 as its address. 
The filtering routine should return via RTL. File type list 
starts with a count byte. Record structure returned is the fol- 
lowing: Open Flag (W); File type (W); Auxiliary file type (W); 
filename (16 bytes); full pathname to file (129 bytes). 

Function: $0A17 
Name: SFPutFile 

Lets the user choose a filename for saving information to disk 
Push: X position of dialog box (W); Y position of dialog box (W); 

Pointer to dialog box title string (L); Pointer to string contain- 
ing original filename (L); Maximum length of name (W); 
Pointer to returned pathname record structure (L) 
Pull: Nothing 
Errors: None 
Comments: Returned record structure is the same as SFGetFile. 

Function: $0B17 
Name: SFPGetFile 

Allows user to choose a filename from a custom dialog box 
Push: X position of dialog box (W); Y position of dialog box (W); 
Pointer to title string (L); Pointer to filtering routine (L); 
Pointer to file type list (L); Pointer to dialog template struc- 
ture (L); Pointer to modal dialog event handler (I); Pointer to 
returned pathname record structure (L) 
Nothing 
None 

Same as SFGetFile except for the template pointer and modal 
dialog activity handler (see Dialog Manager section for 
details). 

$0C17 

SFPPutFile 

Gives the user a custom dialog box to choose a filename for 

saving information to disk. 

Pointer to dialog box title string (L); Pointer to string contain- 
ing original filename (L); Maximum length of name (W); 
Pointer to dialog template structure (L); Pointer to modal dia- 
log event handler (L); Pointer to returned pathname record 
structure (L) 



Pull 

Errors 

Comments 



Function: 
Name: 
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Pull: Nothing 

Errors: None 
Comments: See SFPGetFUe. 

Function: $0D17 
Name: SFAtlCaps 

Sets the case mode for filenames in dialog boxes 
Push: Case flag (W) 
Pull; Nothing 
Errors: None 
Comments: If case flag is true (nonzero), all filenames in SFO dial 
boxes will be shown without conversion to lowercase. 



367 










_- . Appendix A 

Apple's Human Interface 
Guidelines 



The uniting idea behind the Macintosh and Apple tics desktop, win- 
dows, menu bars, icons, and dialog boxes is to give all software 
applications a universal look and feel. Apple wants its computers to 
be easy to learn and to use. To accomplish this, all software should 
follow the same conventions and use the same or similar methods 
of accomplishing many tasks. 



Witness the rabble of MS-DOS software, with its many pro- 
grams and varying uses of graphics, the keyboard, and other 
conflicting methods of operating a program, The Human Inter- 
face Guidelines provide sanity and order in an operating sys- 
tem that might otherwise be just as confusing as the rest. 



Contrary to what you've read, following the guidelines is not 
called user-friendly programming. Instead, Apple refers to it as user- 
centered programming. Most programs are written by programmers 
who wish to amaze other programmers. As a programmer yourself, 

ymi'vp prnhaVily hppn fnmtrafpH with thp way things arp "supprrspH 

to be done using the desktop interface. After all, wouldn't it be 
much easier and faster to type an MS-DOS-like command such as 
COPY A:*.' C: \ROOT \DEV /B? 

Perhaps you have noticed that the user interface of many non- 
Apple programs is poorly thought out. Among the dozens of word 
processors available for MS-DOS computers, there are radically dif- 
ferent procedures to perform the same tasks. Some word processors 
have their own conventions and, for the convenience of users, 
allow alternate keypresses to mimic other word processors. Some 
even have vastly different sequences of commands within a single 
program to achieve similar results. This is the sort of disarray that 
naturally occurs when there is no enforced standard, 

Apple has worked on its Human Interface Guidelines for years. 
The idea behind the guidelines is to make all programs running on 
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Apple computers behave the same, or enough alike that you only 
need to leam one technique for accomplishing similar tasks in sev- 
eral programs. 

This appendix presents certain ideas and philosophies of the 
Human Interface Guidelines. It was decided that these ideas should 
all be placed together here, rather than scattered throughout the 
book. After all, you are a programmer. And usually the last thing 
you'll consider is how the first-time user will feel about using your 
program. Mow that you know how to program the Apple IIGS 
Toolbox, it's time you learned how to present it to the user. 

Programs are not judged on speed alone. Many programmers 
pride themselves in writing fast, compact code. Getting the job 
done, and done quickly, is important. But magazine reviewers and 
software salespeople will not recommend programs that don't fol- 
low these guidelines. 



Reading the Human Interface Guidelines is like reading a dog- 
eared, highlighted college text. The list is full of interesting 
ideas, thoughts, and reasons explaining why Apple did what it 
did in designing the Macintosh/Human interface. 

This book (and its predecessor, COMPUTERS Mastering the 
Apple IIGS Toolbox) constantly reminds you to "follow the con- 
ventions" and "do it this way." If you don't follow the guide- 
lines, you may find your work incompatible with future 
releases of the computer or operating system. 

You'll notice that few programmers obey all of the rules 
and suggestions mentioned in the guidelines. Just as with 
other aspects of life, some people don't pay attention. Apple 
Computer itself is one of the worst offenders and doesn't al- 
ways pay attention to those warnings, either. Just ask anyone 
who owns a Mac 11. Because Apple didn't follow its own rules, 
a good deal of its own software won't work on the Mac II. 

If you buy and read a copy of the Human Interface 
Guidelines, you'll notice that there are many recommendations 
that Apple never follows. The best advice is to do what they 
say and not what they do. Follow the guidelines and you will 
avoid trouble in the future. 
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Apple's Human Interface Guidelines 

What Are the Human Interface Guidelines? 

Addison -Wesley has published a book written by Apple entitled 
Human Interface Guidelines: The Apple Desktop Interface. You can 
buy this book at your favorite bookstore (ISBN 0-201-17753-6). It's 
the latest rendition of an on-going project at Apple. While research- 
ing Advanced Programming Techniques for Mastering the Apple UGS 
Toolbox, we located and mulled over one of the photocopied origi- 
nals of the Human Interface Guidelines. Not much has changed 
since then. Only the list of contributing authors has grown longer. 
Still, most of the work can be attributed to Bruce Tognazzini (also 
lovingly called "Saint" Tognazzini). And before that, much of the 
philosophy on the interface came from work originally done at 
Xerox's Palo Alto Research Center (Xerox PARC). 

Most of the beginning of the book is devoted to philosophizing 
and self-admiration of the Macintosh, mouse, and the desktop in- 
terface. Since you know how to point, click, and drag, that infor- 
mation is left out of this appendix. 

Instead, you'll find the high points of the Human Interface 
Guidelines, all you really need to keep in step with what Apple 
likes to see in Apple programs. If you follow these guidelines, your 
program will be more compatible with other Apple IlGS and Macin- 
tosh programs. And Apple will like you. What more could you 
want? 

The Desktop Environment 

The desktop environment is the latest, supposedly best way for a 
computer to communicate with a human. It's called visual commu- 
nication. Rather than typing names and commands, you do things 

visually with ihc mouse and willi giaphk icuns vvltU.lt appeal un 

the screen. 

You might think that this setup would mean anyone could use 
an Apple computer immediately. You would be wrong. People still 
have hang-ups about computers. No matter how easy you make 
them, some people would have you throw pitchforks at them 
before they would use a computer. 

The following are highlights of the guidelines: 

• Every action on the desktop should be as simple and consistent as 
possible. The Human Interface Guidelines give the greatest weight 
to visual communication, simplicity, and clarity. 
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• Don't be rude to the user. Always provide a way out. When you 
are given the choice between doing something potentially danger- 
ous and backing out, always make the default choice the way out. 
In other words, it should never be easy to do something stupid. 

• Keep your desktop consistent. Changing screen modes is about 
the most unforgivable offense. True, the 320 mode is more color- 
ful, and the 640 mode can display more text. Yet a word processor 
that uses one mode for one thing and the second mode for an- 
other would be dreadful. Users admire stability. 

• Cut down on the dazzle. You can do amazing things with the 
Toolbox and QuickDraw, but try not to overwhelm the user with 
spectacular graphics and stereophonic sound. Look up the word 
aesthetic in the dictionary if you have trouble with what program- 
mers call creeping elegance. 

Programming for the Toolbox 

In case you haven't noticed, all programs written for the Apple IlGS 
Toolbox follow a convention. They consist of a main event loop 
nested between setup and shutdown routines. (See Chapter 3 of 
COMPUTERS Mastering the Apple lies Toolbox for additional infor- 
mation.) This technique makes for better organization of your pro- 
grams, making your programs easier to modify, as well (and 
incidentally, the code is easier to adapt for your other programs). 
The following are a few concepts to keep in mind while de- 
signing and writing your programs: 

• Implement what Apple calls User Control in your programs. Make 
the user choose what goes on. Don't make it appear that there is 
no way to control what the computer is doing, 

• Provide the user with a complete list of options at any decision 
point. This is what separates desktop programs from IBM-type 
programs. In the IBM (command line interface) version of a pro- 
gram, it's up to you to remember what commands to type. With 
an Apple program, the user should see all the options available 
and then visually select one. Avoid hidden or secret options. 

• When using an icon as a switch, make the icon closely resemble 
the action it invokes. For example, icons of an ImageWriter and 
LaserWriter can be used to choose a printer instead of an input 
box with the prompt Enter printer:. 
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• When you provide text (to explain a dialog box or amplify a 
choice, for instance), write a solid, meaningful description. Too 
many programmers opt to be overly cryptic with their text de- 
scriptions. But don't be overly simple with your text, either. No- 
tice how Send the contents of your document to the printer is too 
simple, and Dump File to Printer Device is too complex, but Print 
document: Chapter One? is just right. 

Mouse Traps 

The guidelines go into great detail about use of the mouse, to the 
extent of discussing the algorithms used to select text with the 
mouse. Since this is an internal function of the Toolbox there's no 
need to repeat it here. Instead, the following are the mouse high- 
lights of the guidelines: 

• Using the mouse with your programs should be consistent with 
other desktop programs. Remember the standard mouse opera- 
tions (pointing, clicking, dragging, double-clicking, and so on). 
Don't make up new mouse modes that could confuse the user. 

• Though all Apple computers now have cursor-control keys on 
their keyboards, Apple demands that you never use the arrow 
keys as a replacement for the mouse. Never. You shouldn't even 
use the arrow keys to choose menu selections. (It should be 
pointed out. however, that Apple uses the cursor keys to imitate 
the mouse on the Macintosh.) 

Though you can change the cursor's shape to just about any- 
thing (a pointing finger, for example), the following shapes are sug- 
gested for certain activities: 

Figure A-l. Mouse Pointer (Cursor) Shapes 

^ Arrow 

T Insert Bar 

-♦- Crosshairs 
<3* Plus Sign 
<2> Wriatwatch 
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• The pointer is the most common default cursor. 

• The I-beam is used for inserting and selecting text. The I-beam 
(or, if active, the pointer), disappears when the user starts typing. 

• The crosshairs pointer is used to select graphic shapes for 
manipulation. 

• The plus sign is used in some spreadsheet programs to select cells 
in the worksheet. It can also be used to select fields in an array. 
(The original Macintosh spreadsheet program, Multiplan, first em- 
ployed the plus sign.) 

• The tiny wristwatch stands for a pause as the machine does some 
work behind the scenes. 

Pull-Down Menus 

Menus are among the prime ingredients of the desktop. You should 
already know about menu titles and menu items and where they fit 
into the big picture. Keep in mind that the organization of menus 
and menu items (and command areas) is in your control. 

Standard Menus 

There are three menus most programs should have. For the sake of 
consistency, certain menu items should appear only in these 
menus. The standard menus are 

• The Apple menu 

• The File menu 

• The Edit menu 

Text-based programs can also have Font, Style, and Size 
menus. However, Apple is less fussy about them. 

• The Apple menu is always the First menu on the far left side of 
the menu bar. The first item at the top of this menu is an 
About. . . menu item used to display a dialog box telling about 
your program. 

• Under the About. . . item come the various desk accessories in- 
stalled in your SYSTEM/DESK.ACCS subdirectory. Also, you can 
put a Help item in the Apple menu and any configuration item or 
desk accessories specific to the application, such as a spelling 
checker for a word processor, 

• The File menu contains all the items that deal with saving, load- 
ing, and creating data files. Aside trom its allowances ror opening, 
closing, and saving files, this menu also contains print options 
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and the Quit option. Even if your program lacks any disk access, 
this is where the Quit option should go. The typical file menu ap- 
pears as shown in Figure A-2. 

Figure A-2. Graphic of File Menu 



New 
Open,., 



*v 



Close 

Save 
Sauefts... 
Reuert to Sailed 

Page Setup... 
Prim... 



Quit 



M 






• The final required menu is the Edit menu. A lot of emphasis is 
put on the cut-and-paste aspect of the desktop. Therefore, the 
Edit menu is considered important to all applications. (Even if 
your program doesn't need the items in the Edit menu, you might 
want them included for use by some desk accessories.) 

Figure A-3. Graphic of Edit Menu 







Undo 


*Z 


Cut 
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Copy 


*C 


Poile 


*tl 


Cleat 




Select (in 




Shoui Clipboard 



One of the common items on the Edit menu is Select All, 
There is no key equivalent officially defined for the Select All item, 
although many applications seem to implement their own (usually 
Open Apple-A). 

Other menus that might crop up from time to time, especially 
in text-oriented programs, are 

• The Font menu 

• The Size menu 

• The Style menu 
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There are no hard-and-fast guidelines for these menus. If you 
have a crowded menu bar, you can combine two or three of them 
into one menu, or include all the options in a dialog box that looks 
like a Boeing 747 control panel. 

Menu Items 

The guidelines have the following suggestions for menu items: 

• Menu items can be verbs used to describe an immediate reaction, 
or they can be adjectives used to describe some attribute of a 
selection: 

• With verb menu items, you choose a menu item and that task 
is carried out. If the program requires more input before the ac- 
tion can take place, the menu item should be followed by ellip- 
ses (. . .). If the item toggles a state on or off, a check mark 
should appear to indicate when the item is on, or you can 
choose to change the menu item's text— for example, Inhale 
could be changed to Exhale. 

• When menu items are adjectives (in font menus, for example), 
they should be descriptive words and adequately characterize 
what they change. Consider the opaqueness of a menu entry 
such as Font 2 when it is compared to something more descrip- 
tive, such as Courier. 

A third type of menu, introduced with the Apple IlGS, is the 
color menu, This menu has no words, only the hues of colors avail- 
able for changing selected items. 

Commonly used menu items should be at the top of a menu, 
with less frequently used items at the bottom. Good examples are 
the Undo menu item commonly found at the top of the Edit menu, 
and the Quit menu item found at the bottom of the File menu. 

Key Equivalents 

You can assign key equivalents to just about any menu item. Be 
sure they make sense. Also consider that some actions are appro- 
priate for the mouse and others are appropriate for the keyboard. A 
word processor is keyboard-intensive (although a mouse is great for 
editing). When users are typing, they'll find if more convenient to 
use a keyboard equivalent of a pull-down menu item than to grab 
the mouse, pull down the menu, and make the selection. On the 
other side of the coin, a paint program is a mouse-intensive piece 
of software. Having a keyboard-only command could be awkward, 
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Some of the older Macintosh communications programs lacked 
key equivalents entirely. This was because they used the Com- 
mand key (later the Open Apple key) instead of the Control 
key to generate control codes. Apple 1IG5 communications pro- 
grams have access to both the Open Apple-Command key 
and the Control key. So there is no reason to write a program 
devoid of Apple key equivalents. 



Help 
Copy 
New 


Apple 
Edit 

File 


Open 

Quit 

Save 


File 
File 
File 


Paste 


Edit 


Cut 


Edit 


Undo 


Edit 



The following keyboard equivalents must be used exclusively 
for the function described. Aside from these, you can assign what- 
ever key equivalents your program might require; 

Keyboard Equivalent Comment Menu 

Open Apple-? 
Open Apple-C 
Open Apple-N 
Open Apple-O 
Open Apple-Q 
Open Apple-5 
Open Apple-V 
Open Apple— X 
Open Apple-Z 

Note thai Open Apple-/ is considered Ihe same as Open Apple-? (which is actually Open 
Apple-Shift-/). (Sec Chapter 8 for information on defining these keys.) 

Less stringently obeyed are the following text-style key 

equivalents: 

Keyboard Equivalent Comment 

Open Apple-B Bold 

Open Apple-I Italic 

Open Apple-P Plain 

Open Apple-U Underline 

A special-case Open Apple key equivalent is Open Apple-, 
(Open Apple-period). This key equivalent can be used to halt an 
action such as printing a document or a file listing in the APW 
shell. Apple implemented Open Apple-, because some Macintosh 
keyboards lacked an Esc key (normally Esc would be used). A few 
older programs may stick with the Open Apple-, convention. How- 
ever, if you decide to implement an Esc cancel kev in vour pro- 
grams, you might want to add Open Apple-, just to be well- 
received. 
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Dialog Boxes 

Dialog boxes are actually special forms of windows. They are di- 
vided into modal and modeless types, as well as the special-case 
Alert boxes. The guidelines include the following information about 
dialog boxes: 

• Dialog boxes should be placed in the center of the upper third of 
the screen. (The examples in this book were positioned in the cen- 
ter of the upper half because it was more aesthetically pleasing.) 

• Alert boxes can be positioned so that their default button is in the 
Same position as that occupied by the button that activated them. 
For example, this would allow the user to quickly cancel an oper- 
ation without moving the mouse. 

• A dialog box should always contain a message. It might describe 
what the dialog does or give some indication of what is happen- 
ing. Don't crowd the text into the dialog. If you need more room, 
make the dialog box bigger. 

• The most important and most commonly used items in a dialog 
box should be placed at the top, just as they are in the pull-down 
menu. Less frequently used items should be placed at the bottom. 
You can also place the more important items on the left side of 
the box, and the less important ones on the right. 

• Remember to include in the dialog box a button that lets the user 
out. 

• The OK button is associated with the Return key and the Cancel 
button is associated with the Esc key. Don't confuse the user by 
mixing these up. 

There is such a creature as a dialog box without buttons. An 
example is a simple text box that displays a message and then dis- 
appears. One use for this sort of dialog is to inform the user how 
long an operation will take. For some reason, users don't mind 
waiting 15 minutes for an operation if the program is smart enough 
to tell them to do so. 

Alerts 

An alert dialog box is an example of a specific dialog with a spe- 
cific use. In some cases, you may find that a simple beep of the 
speaker will replace an alert. For example, if a user clicks outside of 
a field, it's much faster to make the speaker bonk than to bring up a 
complete alert box. 



380 



Apple's Human Infer/ace Guidelines 






Take advantage of the various alert stages. During your beta 
testing, you may discover that some alert boxes appear more often 
than others, indicating perhaps that a specific type of error is more 
likely to occur. If so, you may want to rethink your program's strat- 
egy. Ask questions of your beta testers to see if this happens. 

The guidelines make the following suggestions: 

• Keep alerts clean. Don't use radio buttons, long-scrolling text mes- 
sages, check boxes, or other clutter. The typical alert box has an 
alert icon, a short message (or warning), and two buttons. 

• The two buttons in an alert box typically allow the chosen action 
to continue or to be stopped. For example, an alert might display 
the message Erase your hard disk? The two buttons could be Yes 
and No, or even better, Erase and Stop. Typically, however, you 
should phrase your prompts so that it would be natural to supply 
buttons marked OK and Cancel. 

• The default button in an alert box is always Cancel. The purpose 
of the alert is to warn of some impending danger. The default 
choice should always be to back away from the danger — in other 
words, make users really think about what they're doing. 

• The alert message could be a system error, or something that your 
program can't handle. When this is the case, you may want to re- 
think your error-trapping routines and perhaps take the error- 
correcting decision out of the user's hands. 

Notes on Sound and Color 

The Apple IlGS comes with excellent sound and graphics. With the 
addition of the Mac II, sound and color have also been made avail- 
able to the Macintosh line of computers. 

The following are the guidelines on the use of sound and color 
in your programs. Generally speaking, the suggestions themselves 
are rather obvious, if you think about them. Listed below are only 
the high points. 

Sound. The general thrust of the guidelines approach to sound 
is that sound should be used as an attention-getter. Use sound to 
say Hey you! should an application require immediate attention, or 
use it to alert the user that something is happening in the back- 
ground. Other highlights: 

• Try not to startle the user with sound. 
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- Different sounds can be used to herald entering and exiting cer- 
tain modes. Of course, you may find these modal sounds annoy- 
ing. It would be nice to include an option in your program for 
shutting off the noises (or for a volume control, at least). 

Color. Color can be fun, and a great benefit to your programs. 
However, there are a few guidelines about the use of color. Most of 
these you can figure out on your own. For instance, an all-red fore- 
ground and background can make computing difficult. Still, some 
of the other guidelines are interesting and, when you pause to 
think about them, make sense. 

• Different colors can be used in a number of ways. For example, 
you can color some text or a dialog box icon red to indicate some- 
thing drastic. The color yellow can be used to show caution. 
Green is used to indicate go or proceed, 

. Blue, especially light blue, is hard to see, and the guidelines rec- 
ommend avoiding its use. However, an example of a good use of 
light blue would be providing rules or grids for a paint program; 
the blue is just faint enough to use as a reference. 

• Use color to show how certain objects are grouped together, or to 
define separate areas. 

. Keep the background light. A dark red background will make any 
foreground text difficult to see. Some programmers get carried 
aWy W\fo O&M. teflfcmfcitt ttat ySfiJCS iust want to use your pro- 
gram. Psychedelic colors went out with the sixties, along with 
love beads and sandalwood incense. 

Above all, consider the application. Colored text looks good on 
the screen (and has probably sold more than one Apple IlGS). 
However, few people can print colored text. If the application ts 
one that could use some color— such as a drawing, painting, or 
educational program— use it. But for text-intensive programs think 
twice before splashing the screen with color, or at least pro Vl de the 
user with the option of choosing the colors to be used on the text 
display. 
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It should be noted that the terms text and text display have 
been tossed about freely in this appendix. True, the Apple IlGS 
does have a text display mode that can use different-colored 
b/stVjgi'W.Trtlft my& VfcVass. 8mA *& ntfe.iwfias to text are maanJ 

to include any textual material displayed on the graphics 

screen as well. 



Summary 

It goes without saying that a copy of the Apple Human Interface 
Guidelines will provide more detailed information than this appen- 
dix. However, the desktop environment is constantly changing. As 
Apple develops the IlGS and its other computers, and as program- 
mers provide more interesting and intuitive applications, the guide- 
lines will no doubt change. Just remember these two things: 

• Users love to play with things. 

• Above all, have fun with your programming. 
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Table B-1. Tool Sets 



Number 


Tool Set Name 


Version 


SOI 


Tool Locator 


$0201 


S02 


Memory Manager 


$0200 


$03 


Miscellaneous 


$0200 


S04 


QuickDraw 11 


$0202 


$05 


Desk Manager 


$0202 


$06 


Event Manager 


$0201 


$07 


Scheduler 


$0200 


$08 


Sound Manager 


$0201 


$09 


Apple DeskTop Bus 


$0201 


$0A 


SANE 


$0202 


$0B 


Integer Math 


$0200 


$0C 


Text Tool Set 


$0200 


SOD 


RAM Disk 


$0200 


$0E 


Window Manager 


$0201 


$0F 


Menu Manager 


$0200 


$10 


Control Manager 


$0202 


$1] 


System Loader 


■> 


$12 


QuickDraw It Auxiliary 


$0202 


$13 


Print Manager 


$0102 


$14 


LineEdit 


$0200 


$15 


Dialog Manager 


$0200 


$16 


Scrap Manager 


$0102 


$17 


Standard File 


$0200 


$18 


Disk Utilities 


7 


$19 


Note Synthesizer 


$0100 


$1A 


Note Sequencer 


— ? — 


$1B 


Font Manager 


$0203 


$1C 


List Manager 


$0201 



The high-order byte of the version number indicates the major 
release number and the low-order byte is the minor release. If bit 7 
of the major release is set (bit 15 of the word), the release is a beta 
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version. For example, $0201 (binary 0000 0010 0000 0001) indi- 
cates version 2.1, and $8101 (binary 1000 0001 0000 0001) indi- 
cates beta (prerelease) version 1.1. 

The version numbers above apply to the ROM 01 release of 
the Apple IIgs as well as to the tool sets on System Disk version 
3.1. Version numbers shown as — ?— indicate tool sets which are 
not yet available. 

TV.C Program 

Since version numbers change as fast as the wind in Cupertino, 
Program B-l (a C program) will generate a table just like the one 
printed above with the latest tool set version information for your 
system. 

Program B-l. TV.C 

,, -_« 















14. 


o. 


/« Window Manager •/ 


15. 


0, 


/« Menu Manager «/ 


16, 


0, 


ft Control Manager */ 


18, 


o, 


/* QD II Auk */ 


19, 


0, 


/* Print Manager »/ 


20, 


o, 


/( Line Edit */ 


21, 


o, 


/t Dialog Manager »/ 


22, 


0, 


/* Scrap Manager */ 


23, 


0, 


/% Standard File V 


25, 


0, 


/« Note Synth «/ 


27, 


0, 


/* Font Manager */ 


2a, 





/* List Manager */ 



Displays all known toolaet versions » 



CjuiUVc (Pans = { NULL, 1; /» ProDOS 16 Quit paramster list »/ 



• irclude <typeB.h> 
•include <prodos.h> 
•include ant«ath.h> 
(include <locator,h> 
(include <me™or}r.h> 
♦include <nuBctool -h> 
(include <texttool.h> 

* Main 



■ainO 

( 



TLStartUp (); 

UserlD ■ MrBtartUp (); 

MTStartUp {)] 

WriteStrlng (ApLoading tools. 

LoadTooU (Tooliat) : 

WriteLine t"\p"K 

WriteLine ("\p"); 



—»/ 



BrrChkO: 
BrrChkl H 

BrrChMt: 

BrrChkO; 



/* Show Versions •/ 



j 



Word UaerlD; /« Our User ID »/ 

Word ToolUtl 1 = < 

12, /» Tool Count »/ 
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MTShutDown t ) : 
ttChuUtown (User ID); 
TLShutDown < > ; 
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Tnnl ^£»tc m fhp Annfp IJH9 Tnnlhnv — — 




J UUl OVlb ill l((" /\^J^J1G IILjo IUUfiUI>A 






QUIT IHPajw); /* quit to ProDOS «/ 

1 






/«- * 






« Handle Toolbox Errors « 






. ./ 






ErrChkO 1 if C.toolErr) SynFaLlH«r<_toalErr, NULL!; 1 






/* — * 






* Show Tooloet Versiona * 






strict set ( 






char *nane ; 






word, id; 






| Toolset! 1 = I 






"\pTool Locator", L, 






\FTfcmory Manager", 2> 






"\pMiscellaneous Tools", 3, 






"NpQuLckCraw 11". 4. 






"\pDesW Manager", 5, 






"\pEvent Hnnattei ■" , 6, 






"\pScheduler" , 7, 






"\pSouivl Mana|t«»r" , 8, 






"\pApple Desktop Huh", 9, 






"VpSANK", 10, 






"\plnteger Math", 11, 






"\pText Tooloet" , 12, 






"\pRAM Disk", 13, 






"\pWirdow Manager", M, 






"\pMenu Manager", 15, 




A 
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"\pControl Manager". 


16. 


"VpSystem Loader", 


17, 


"SpQuickDraw 11 Aux.", 


IS, 


"\pPrint Manager", 


19, 


"\pLineBdit", 


20, 


"\pDiaIog Manager", 


21, 


"Spaorap Manager", 


22, 


"\pStandard Kile", 


23, 


"\pDisk Utilities" . 


24, 


"VpNote Synthesizer", 


25, 


"SpNote Sequencer", 


26, 


"\pPont Manager", 


27, 


"\pList Manager", 


28 



♦define BNnilES (sjteof (Toolset) / siieof (struct set) 

char »He>Str = "\ptxxxx"; 

char «Title = "\pNo. Toolaet Name Veraic 

ShouVera!) 
I 

word i ; 

WnteString (Title); WriteLine (Title); 
RepeatChar ('=", 71); WriteLine «"\p"); 

for (i = 0; i < BHTRIBS/2; M-i) ( 
DoLine (i); 



"I \f 



Tool Sets in the Apple lies Toolbox 



RepestChar (32, 6 | : 
OoUne (i * IOTRIb5/2>: 
WriUsLine Op"); 



DoLine(itea) 

word linn; 




word id, v«r; 

id = Toolaetlite*].id. 
IntZHex (id, HexStr+2, 2); 
HexStr(5] = HexStr(4) = 32; 
Writefltring (HexStr); 
WriteStrina (ToolsetUteal.naae) ; 
RepeatChar (32, 22 - < Toolset [it«»l , 

Ida id 

ora H024 

tax 

pha 

jal di«pat«3her 

Bta _toolErr 

pla 

Bta ver 
I 
if C_tooJErr> 

WriteString l"\P — f — ">; 



i[0] a Ojrff)>; 
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Int2Hex (ver, HexStw-2, 4); 
WriteString (HexStrl; 



RepeatChar (theChar, count) 
char theChar ; 
int count; 
I 

while (count — ) HriteChar (theChar I; 
I 



This program makes a handy utility to keep around on your APW 
system disk. To direct its output to a file or printer, use one of 
these APW shell commands; 

tv > filename 
tv >. printer 
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J.nL2Hex (ver, HexStr*2, 4>; 

WriteString IHexStr); 



RepeatChar (theChar, count! 
char theChar; 
int count ; 

1 

while (count — ) WriteChar (theChar); 



I 



This program makes a handy utility to keep around on your APW 
system disk. To direct its output to a file or printer, use one of 
these APW shell commands: 

tv > filename 
tv >. printer 



390 



Appendix C 



Error Handling 



There are several ways to deal with errors returned from the Tool- 
box. A blanket method has been shown in this book, one that's not 
really the best way to deal with potential errors. In fact, the method 
used by most Toolbox program examples in this book would be 
considered awful error trapping for a professional application. 

Most of your programs should be smart enough to catch sim- 
ple, common errors. Out-of-memory errors, disk I/O errors, and 
some Toolbox errors can easily be sidestepped. Your programs 
should make exceptions for the errors, recognize them, and deal 
with them in such a manner as to be transparent to the user. In 
other words, don't cop out on error handling. 

ErrChk 

Program C-l is the error-checking code used in this book as the ge- 
neric error handler, ErrChk, The problem with ErrChk is that it as- 
sumes every error returned from the Toolbox is a fatal, typically 
death-inducing error. 

Program C-l. ErrChk in Machine Language 



Handle Toolbox Errora 



BrrChk bca Die 



rta 



pha 

puahlong *0 
SyaFailmr 



;Carry aet if error 

;£lse, return 

[Toolbox returns error in A 

;Vae standard aystea death nesefule 

;Oet reedy to slide apples bach and forth 
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Program C-2 is the equivalent in C. 

Program C-Z. ErrChk in C 

/« 1 



Handle Toolbox Errors 



-*f 



ErrChk() 

I 

ir (_toolBtT> 3ysP»ilrt*r<_toolBrr. nil): 

) 

Program C-3 is the equivalent in Pascal. 
Program C-3. ErrChk in Pascal 



/i Check for error, die if bo */ 



Handle Toolbox Errors * 



I Check For error, die if no I 



PROCEDURE ErrChk; 
BEGIN 

IF IsToolError TH0J 

Sy*FailMa:r(ToolBrrorNijB], 3trinSPtr(0|i ) ; 
END; 



This error handler is called after every potential error-causing Tool- 
box function. All it checks is whether an error occurred. If so, the 
program bombs using the SysFailMgr call and tells you there's a fa- 
tal error. This is a very nondescript and somewhat crude method of 
error handling, albeit good for quick demonstrations and beta test- 
ing. But it doesn't take into consideration errors from which recov- 
ery is possible. 
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A Better Generic Error Handler 

Documenting a procedure for each nonfatal Toolbox error would be 
complicated and would increase the size of this appendix to a full- 
blown chapter. Instead, the following example is provided to pique 
your curiosity. 

This error-trapping routine (Program C-4) is designed to han- 
dle generic errors, and it can replace the ErrChk routine used 
throughout this book. Of course, it's a good idea to take care of 
nonfatal errors individually. This routine should be called only as a 
last-ditch effort. The code is listed in machine language. C and Pas- 
cal programmers can be inventive and code their own versions. 

Program C-4. Fatal Error Handler 



Fatal Error Handler 



;only absolutely fatal errors are sent here 



pka 


•.Toolbox returns error in A, save it 


and MFPOO 


;get toolset nuaber 


xba 


lexchanSe MSB half of A-rea to LSB 


olc 


;clear carry 


Mo- 


;put a into ¥ 


lds rTsble-28 


^offset froa Btart of table 


adc 128 


; length of each entry 


dey 


;d*Q court 


bne DieO 


'■loop until the toolset 1b indexed 


phta 


; push data bank twice 


phb 


; (because phb pushes only a byte* 


pha 


Ipush string's address 


.SysFailMgr 


;Cet ready to slide applea back and forth 
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Table str ' Tool Locator error •' 

str ' rte*ory Manager error ** 

str 'Miscellaneous Tool* error J' 
str ' QuickDraw II error *' 



■tr ' 


Desk Manager error $' 


Btr ' 


Event Manager error *' 


str ' 


Scheduler error J" 


Btr ' 


Sound Manager error *' 


str ' 


Apple Desktop Bus error »' 


Btr ' 


SANE error $' 


str ' 


Integer Hath error J ' 


atr ' 


Text Toolset error S' 


Btr ' 


RAM Dink error 1* 


etc 


Window Manager error »' 


atr * 


Menu Manager error S' 


atr 


Control Manager error »■ 



■tr ' Sy*te» leader error »' 

atr ' QuickDraw ii Aux- error *' 

atr ' Print Manager error $' 

atr ' LineEdit error i' 

atr ' Dialog Manager error $' 

str ' Scrap Manager error »' 

atr ' Standard File error S' 

atr J Disk Utilities error *' 

atr ' Note Synthesizer error »' 

str ' Note Sequencer error *' 

atr ' Font Manager error f ' 

atr ' List Manager error I' 



Error Hu nc/Jing 






This routine eliminates the Fatal System Error message and replaces 
it with something more specific. Rather than providing a two-byte 
hex number, this example translates the first number, representing 
the tool set, into a string. The actual error number is displayed after 
the dollar sign. So instead of 

Fatal System Error — > I0EQ2 

you are given 

Window Manager error *0EO2 

Granted, this routine doesn't do anything the standard ErrChk 
routine didn't do, but it's more specific as to the type of error oc- 
curring. Again, a specific routine to deal with certain types of errors 
would be better. 

This routine is still relatively simple. It would be easy to make 
it more elegant. For example, rather than padding each error string 
so that each takes up a fixed number of characters, you could use a 
table of pointers into variable length strings. It takes more source 
code to implement, but results in far less object code. 



^ 
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Error Codes 



There are three types of errors you can receive from your com- 
puter. Unfortunately, it's sometimes hard to determine the origin of 
an error, though this appendix should help, The three types of er- 
rors you can receive are 

• Fatal System errors 

• ProDOS errors 

• Toolbox errors 

Fatal System errors are errors your programs won't be able to 
catch or wouldn't want to catch. Because these errors seem to pop 
up quite often for adventurous programmers such as yourself, 
they're listed here. 

ProDOS errors are different from Toolbox errors in that their 
origins are in ProDOS and are not the result of any Toolbox mis- 
takes you might have made. In fact, anyone who has programmed 
disk I/O or worked at all with any operating system is familiar 
with a DOS error. You can't build a decent program without DOS 
error trapping. 

ProDOS errors are not incurable. For example, if your program 
returned the error Disk Write Protected, you could prompt the user 
to remove the write-protect tab or use another disk. 

Toolbox errors aren't always fatal. In fact, quite a few are sur- 
vivable (see Appendix C). However, more often than not, your pro- 
gram's error-handling routine may report a few of the more 
interesting ones. If your error-handling routine is smart, it can work 
around the error. Otherwise, make sure your program displays the 
error code so your users can report it back to you. 



Just to throw you a curve, there are some Toolbox function 
calls that result in errors originating from ProDOS. Yes, it's 
true. For example, the Tool Locator's LoadTools call or the 
Font Manager's FMStartUp function can return with an error 
flagged. An error code between $0001 and $00FF is a ProDOS 
16 error. Error codes greater than $00FF are Toolbox errors. 
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Table D-l. Fatal System Errors 




SOI 
$0A 


Unclaimed interrupt 

Volume control block unusable 




SOB 


File control block unusable 




$0C 


Block allocated illegally 




SOD 
111 

TabI 


Interrupt occurred while I/O shadowing off 
Wrong OS version 




s D-2. Errors Returned from ProDOS 




$00 


No error 




$01 


Invalid call number 




$07 
$10 


ProDOS is busy 
Device not found 




$11 


Invalid device request 




$25 

$27 


Interrupt vector table full 
I/O error 




$28 


No device connected 




S2B 

$2E 


Disk is write-protected 
Disk switched, files open 




S2F 


Device not online 




$30-$3F Device-specific errors 




$40 

S42 


Invalid pathname 




File control block table lull 




$43 


Invalid reference number 




$44 


Path not found 




$45 


Volume not found 




$46 


File not found 




$47 
$48 


Duplicate pathname 
Volume full 




$49 
$4A 


Volume directory full 
Version error 




$4B 
S4C 


Unsupported storage type 
EOF encountered, out of data 




$4D 


Position out of range 




$4E 


Access: file not rename-enabled 




$50 
$51 
$52 
$53 
$54 


File is open 

Directory structure damaged 

Unsupported volume type 

Invalid parameter 

Out of memory 




$55 


Volume control block full 




$57 


Duplicate volume 




$58 


Not a block device 


397 













• Appendix D 


$59 


Invalid file level 


S5A 


Block number out of range 


S5B 


Illegal pathname change 


$sc 


Not an executable file 


$5D 


File system not available 


$5E 


Cannot deallocate /RAM 


$5F 


Return stack overflow 


$60 


Data unavailable 


Table D-3. Errors Returned from the Toolbox 


50000 


No error 


$0001 


Internal error, not enough arguments on the stack 


$0002 


Tool set wasn't activated (no StartUp call was made) 


$0100 


Unable to mount system startup volume 


$0110 


Bad tool set version number 


$0201 


Unable to allocate block 


$0202 


Illegal operation on an empty handle 


$0203 


Empty handle expected for this operation 


$0204 


Illegal operation on a locked or immovable block 


$0205 


Attempt to purge an unpurgeable block 


$0206 


Invalid handle given 


$0207 


Invalid User ID given 


10208 


Operation illegal on block specified attributes 


$0301 


Bad input parameter 


$0302 


No device for input parameter 


$0303 


Task is already in the heartbeat queue 


$0304 


No signature in task header was detected 


$0305 


Damaged queue was detected during insert or delete 


$0306 


Task was not found during delete 


$0307 


Firmware task was unsuccessful 


$0308 


Detected damaged heartbeat queue 


$0309 


Attempted dispatch to a device that is disconnected 


$030 B 


ID tag not available 


$0401 


QuickDraw already initialized 


$0402 


Cannot reset 


$0403 


QuickDraw is not initialized 


$0410 


Screen is reserved 


$0411 


Bad rectangle 


$0420 


Chunkiness is not equal 


$0430 


Region is already open 


$0431 


Region is not open 


$0432 


Region scan overflow 
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$0433 Region is full 




$0440 Poly is already open 




$0441 Poly is not open 




$0442 Poly is too big 




$0450 Bad table number 




$0451 Bad color number 




$0452 Bad scan line 




$0510 Desk accessory is not available 




$0511 Window pointer does not belong to the NDA 




$0601 The Event Manager has already been started 




$0602 Reset error 




$0603 The Event Manager is not active 




$0604 Bad event code number (greater than 15) 




$0605 Bad button number value 




$0606 Queue size greater than 3639 




$0607 No memory for event queue 




$0681 Fatal error: event queue is damaged 




$0682 Fatal error: event queue handle is damaged 




$0810 No DOC chip or RAM found 




$0811 DOC address range en 




$0812 No SAppInt call made 




$0813 Invalid generator number 




$0814 Synthesizer mode error 




$0815 Generator busy error 




$0817 Master IRQ not assigned 




$0818 Sound Tools already started 




$08FF Fatal error: unclaimed sound interrupt 




$0910 Command not completed 




$0982 Busy, command pending 




$0983 Device not present at address 




$0984 List is full 




$0B01 Bad input parameter 




$0B02 Illegal character in input string 




$0B03 Integer or long-integer overflow 




$0BO4 String overflow 




$OE01 First word of parameter list is the wrong size 




$0EO2 Unable to allocate window record 




$0EO3 Bits 14-31 not clear in task mask 




$ 1 101 Segment or entry not found 




$1 102 Incompatible object module format (OMF) version 




$1104 File is not a load file 




$1105 System Loader is busv 
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$1107 
$1108 
$1109 
S110A 

S110B 

$1401 

$1402 
$1404 

$150A 
$150B 
$150C 
$150D 

$1610 

SlBOl 

S1B02 

S1B03 

SI BO 4 

$1B05 

J1B06 

$1B07 

$1B08 

$1B09 

$1B0A 

$1B0B 

$1C01 



Appendix D 

File version error 

UserlD error 

Segment number is out of sequence 

Illegal load record found 

Load segment is foreign 

The LEStartUp call has already been made 

Reset error 

The desk scrap is too big 

Bad item type 
New item failed 
Item not found 
Not a modal dialog 

Unknown scrap type 

Font Manager has already been started 

Can't reset Font Manager 

Font Manager is not active 

Family not found 

Font not found 

Font is not in memory 

System font cannot be purgeable 

Illegal family number 

Illegal size 

Illegal name length 

FixFontMenu never called 

Unable to create list control or scroll bar control 



» 
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Event and TaskMaster Codes 



Programs written for the Apple llGS Toolbox center themselves on 
one event-oriented loop. Everything that happens in your programs 
is based upon a certain event — a mouse click, a drag, a selection. 
The Event Manager and its cousin the TaskMaster are at the heart 
of most DeskTop applications. 

These events provide user input to your program, To deter 
mine which event has taken place (a mouse click, menu selection, 
or press of a key), your program makes a call to either the Event 
Manager's GetNextEvent function, or the Window Manager's Task- 
Master function. Both of these procedures are covered within (his 
book. 

The Event Manager 

The primary function of the Event Manager is GetNextEvent: 

Function: $0A06 

Name: GetNextEvent 

Returns the status of the event queue. 
Push: Result Space (W); Event Mask (W); Event Record (L) 
Pull: Logical Result (W) 
Errors: None 
Comments: If the Result is a logical true, an event is available. The event 
is then removed from the queue. 

GetNextEvent deals with two items, the event mask and the 
event record. The event mask is used to scan only for specific types 
of events. The event record contains information about the event 
when GetNextEvent returns a logical true. 

The event mask. The event mask is a word-sized value used 

to filter out certain types of events, By setting specific bits in the 

event mask, your program can direct GetNextEvent to return only 
the results of specific events. The following chart shows which bits 
in the event mask affect which events. 



401 



Appendix E 



Table E-1. Bit in Ihe Event Mask 

Bit Events Scanned for, if Set 

Not used 

1 Mouse- down events 

2 Mouse- up events 

3 Keyboard (key-down) events 

4 Not used 

5 Auto-key events 

6 Update events 

7 Not used 

8 Activate events 

9 Switch events 

10 Desk accessory events 

11 Device drive events 

12 User-defined events 

13 User-defined events 

14 User-defined events 

15 User-defined events 



When GetNextEvent returns a true value, the event record will 
contain information detailing the event. 

Figure E-1, The Event Record 





Finl Vort 


■KCll Verl 


What 


Event Code 


Message 


Event Message (vanes) 


When 


Clock flriu suet startup 


Where 


Mouse's V position 


Mouse's K position 


Modifiers 


Evtm deouls 





The Event Record 
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The structure of the event record is as shown in Table E-2. 
Tabic E-2. Structure of Event Record 

Field Size Description 

What Word Code describing event 

Message Long Value or pointer providing more detail about the 

event 
When Long Number of clock ticks since the computer was started 

Where Long Two word values; the Y and X position of the mouse 

at the time of the event 
Modifiers Word Describes the state of certain keys, the mouse button, 

and other information 

What. The What field contains the event code. This describes 
which event took place. The events are numbered 0-15 (these are 
not bit values). The value found in the What field will be one of 
those shown in Table E-3. 

Table E-3. Events in What Field 



Event Code 


1 

2 
3 
4 
5 

6 

7 

8 



10 

11 
12 

13 
14 

15 



Description 

Null Event: Nothing has happened. 

The mouse button was just pressed. 

The mouse button has been released. 

A key on the keyboard is being pressed. 

Not used. 

Auto-key event: a key is being held down. 

Update event: a window is being changed, redrawn, sized, 

or its contents updated. 

Not used. 

Activate event: generated when a window becomes either 

active or inactive. 

Switch event: activated when one program switches control 

to another. 

Control-Open Apple-Esc has been pressed (this event is 

handled by the Desk Manager). 

A device driver has generated an event. 

User-defined (can be defined by your application) 

User-defined. 

User-defined 

User-defined. 



Message. The Message field's value depends on the event code 
found in the What field. 
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Event and TaskMaster Codes 



Table E-4. Message Returned 

Evenl Code Message Field Contents 






Undefined. 

1 Button number (low-order word only). 

2 Button number (low-order word only). 

3 ASCII character (lowest byte only). 

4 Undefined. 

5 ASCII character (lowest byte only). 

6 Window pointer. 

7 Undefined. 

8 Window pointer. 

9 Undefined. 

10 Undefined. 

1 1 Value is returned from the device driver. 

12 Value is returned from the user-defined application. 

13 Value is returned from the user-defined application. 
| 4 Value is returned from the user-defined application. 
15 Value is returned from the user-defined application. 

When. The When field contains the number of clock ticks 
since the computer was started. Each tick equals 1/60 second. 

Where. The Where field gives the location of the mouse 
pointer at the time of the event, even if the event isn't mouse- 
oriented. The first word of the Where field contains the mouse's Y 
(vertical) position; the second word contains the mouse's X (hori- 
zontal) position. 

Modifiers. The Modifiers field allows further description of the 

event pulled from the event queue. 
Table E-5. Modifiers 






Bit 





Description 

If set, the window pointed to in Message field is being deactivated; 

otherwise, the window is activated. 

If set, the active window is changing from the system window to an 

application's window, or vice versa. 

Not used. 

Not used. 

Not used. 

Not used. 

If set, mouse button number 1 is down 

If set, mouse button number is down. 

If set, the Open Apple key is down. 

If set, a 5hift key is down. 
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Bit Description 

10 If set, the Caps Lock key is down. 

1 1 If set, the "option" (Solid Apple) key is down. 

12 If set, the Control key is down. 

13 If set, a key on the keypad is down. 

14 Not used. 

15 Not used. 

TaskMaster 

TaskMaster, though a function of the Window Manager, is similar 
to GetNextEvent. It adds extra functions for managing windows 
and pull-down menus and, secretly, calls GetNextEvent internally: 

Function: SI DOE 
Name: TaskMaster 

Returns status of the event queue as well as checks for cer- 
tain window/menu events, 
Push: Result Space (W); Event Mask (W); Event Record (L) 
Pull: Extended Event Code (W) 
Errors: $0E03 

TaskMaster uses the same event mask as described above. It 
adds, however, two fields to the event record, TaskData and 
TaskMask: 

Figure E-2. Event Record with TaskMaster Fields Added 



What 


Evrm Coin 




Message 


Evtfil Mwwge (vwtii 


When 


Clock ocks ioct samp 


Where 


Moum'j y position 


Mora "j X posinon 


Modifiers 


Emu details 




TaskData 


Addioon&l information liom TukMufer 


TaskMask 


Evsnu TwfcMwBi vill scan foi 



The Event Record plus 
TaskMaster Fields 
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Extended event codes. Unlike GetNextEvent, which returns a 
true or false value, TaskMaster returns either an event code or 0, 
When an event occurs, TaskMaster returns a value representing the 
event code. This code incorporates all the values found in the What 
field of the event record after a GetNextEvent function, plus 13 ex- 
tended events. 

Remember, the event codes are returned from the Toolbox 
when TaskMaster is called. You don't have to examine the What 
field of the Event Record, as is done with GetNextEvent, to deter- 
mine which event took place. 

The 13 extra values, or extended event codes, are shown in Ta- 
ble E-6. 

Tabic E-6. Extended Event Codes 

Event Code Description 

16 Mouse is in desk. 

17 A menu item was selected, 

18 Mouse is in the system window. 

19 Mouse is in the content of a window. 

20 Mouse is in drag. 

21 Mouse is in grow. 

22 Mouse is in goai 

23 Mouse is in zoom. 

24 Mouse is in info bar. 

25 Mouse is in vertical scroll. 

26 Mouse is in horizontal scroll. 

27 Mouse is in frame, 

28 Mouse is in drop. 

TaskData. The two extra fields on the event record help to 
further describe the above codes. TaskData contains additional 
information about the extended event code. For the standard event 
codes 0-15, TaskData will be blank. But for the extended event 
codes 16-28, Task Data contains the values shown in Table E-7. 

Table E-7. Meaning of TaskData 



Code 


TaskData Values 




16 


Not used 




17 


Not used 




18 


Not used 




19 


Not used 




20 


HOW ■= Menu ID, LUV\ - 


■ suuuu 
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L,vvm emu 


lasKMastei 


Code 


TaskData Values 




21 


HOW = Menu ID, LOW = 


- Menu Item 


22 


Window pointer 




23 


Window pointer 




24 


Window pointer 




25 


Window pointer 




26 


Window pointer 




27 


Window pointer 




28 


Window pointer 





See examples from Chapters 8 and 9 on how this field is used. 

TaskMask. The TaskMask field is similar to the event mask 
It's used to filter out certain types of events monitored by the Task- 
Master. These events are above and beyond those already filtered 
by the event mask. Both an event mask and a TaskMask are re- 
quired by TaskMaster. 

By setting specific bits in the TaskMask, your program can di- 
rect TaskMaster to return only the results of specific events. Table 
E-8 shows which bits in the TaskMask field affect which events. 
Note that bits 13-31 must always be set to 0, or an error results. 

Table E-8. Bits in TaskMask 



Bit 


TaskMaster Scans for, if Set 





MenuKey: menu item key equivalents 


1 


Update handling 


2 


FindWindow: mouse click in a window 


3 


MenuSelect: choosing a menu item 


4 


OpenNDA: new desk accessories in the Apple menu 


5 


System click 


6 


Drag window 


7 


Select window 


8 


Track goaway button 


9 


Track zoom button 


10 


Grow window 


11 


Allow scrolling 


12 


Handle special menu items 


13-31 


Must be set to 



It's generally a good idea to set all the important bits. When 
this field is set to a value of S000003FFF, it will scan for and be 
able to handle all conceivable events. 
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QuickDraw II Color Information 

In the current version of the Apple IlGS, the color tables used by- 
QuickDraw II are stored at the following addresses. Each color ta- 
ble is $20 bytes long. (These address may change with future re- 
leases of the Apple IlGS ROMs): 

Table F-1. Color Table Locations 
Color Table Address 



9 
10 
11 
12 
13 
14 
15 



SE19E0O 
SE19E20 
$E19E40 
SE19E60 
SE19E80 
$E19EA0 
$E19EC0 
$E19EE0 
$E19F00 
SE19F20 
SE19F40 
$E19F60 
$E19F80 
SE19FA0 
$E19FC0 
$E19FE0 



Colors in the 320 mode. In the 320 mode, nibble positions for 
each color are as follows: 



Table F-2. Color Nibble Positions 



Color Value 
Blue 
Green 
Red 



Low Intensity 

$0001 

$0010 
$0100 



High Intensity 

S000F 
$O0F0 
$0F00 



A color value of $0000 is black (all three colors are turned off) 
A color value of $0FFF is white (all three colors are at their highest 
intensity). Note how each color has 16 steps of intensity (from $0 

to $F). ' 
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Table F-3, Standard Color 


Table in 320 


Color Value 


Color Number 


Setting 


Black 







$0000 


Dark Gray 


1 




$0777 


Brown 


2 




$0841 


Purple 


3 




$07C2 


Blue 


4 




$0OOF 


Dark Green 


5 




$0080 


Orange 


6 




$0F70 


Red 


7 




$0D0O 


Beige 


8 




S0FA9 


Yellow 


9 




$0FF0 


Green 


10 




$00E0 


Light Blue 


11 




$04DF 


Lilac 


12 




$0DAF 


Periwinkle 


13 




$078 F 


Light Gray 


14 




$0CCC 


White 


15 




$0FFF 



Colors in the 640 mode. In the 640 mode, nibble positions for 
each color are as follows: 

Table F-4. Color Nibble Positions 

Color Value 

Blue $000F 

Green $O0F0 

Red $OF00 

Unlike the 320 mode, there are only two values for each color 
in the 640 mode: $0 for off and $F for on. 

Table F-5, Standard Color Table in 640 Mode 



Color Value 


Color Number 


Settin 


Black 





$0000 


Red 


1 


$0F00 


Green 


2 


$00 F0 


White 


3 


JOFFF 


Black 


4 


$0000 


Blue 


5 


S000F 


Yellow 


6 


$0FF0 


White 


7 


S0FFF 


Black 


B 


$0000 


Red 


9 


S0F00 
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Color Value 


Color Number 


Setting 


Green 


10 


$00FO 


White 


11 


$0FFF 


Black 


12 


$0000 


Blue 


13 


$000F 


Yellow 


14 


$0FF0 


White 


15 


$0FFF 
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DeskTop 77-94, S73 74 




check box 249-51 


menus and 114 




color table 250-51 


DeskTop program, parts of 80-81 




items 249 


DeskTop program*, sample &1-94 




CloseDialog function 199 204 


dialog box 187-239 




CloseWindow function 151-52 


closing 245 




closing 


controls 193-98 




dialog box 245 


modal 190, 192, 200-201 
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modeless 190. 192, 217-25 
placing on screen 198-209 
planning Em I I 

programming standards for 380-81 
types of 1 88 
way laige 229 
Dialog Manager 188-93 

requirements lor starting 188-89 
DialogSclect function 219 
DialogShntdown function 189 
Dlalog5tartUp function 189 
directory record 346-47 
direct pages 53 
disk 

contents, ProDOS 16 33-35 

odes. List of 363-64 
tool sets 53-55 

.. I landle function 107 
dithering 12 

DOC (Digital Oscillator Chip) 15-16 
DrawMenuBar function 123 
DrefCom 199 

edit lines, scroll bar 257-58 
equate files, APW assembler 65 -6b 
ErrChk C program 392 
ErrChk ML program 391 
ErrChk Pascal program 392 
error codes 396-400 
disk hst of 363-64 

■ handling 391-98 
C56 
Pascal 56 
errors 

fatal system, list < 
ProDOS 16 and 334-35, 397-98 
Toolbox 55-56. 398-4011 
Event Manager 79, 401-5 
event mask 401-2 
event record 124. 403 
false value 6 

Fatal Error Handler Ml. program 393-95 
file manipula 
filenames, ProDOS 160 
Finder program 23. 36 

i ' i. nuBar function 123 
Font Manager tool set 330 
function 
hst 57-59 
number, tool set ■; ■; 
functions 

ProDOS 16 33 
standard, tool set 50 5 1 
Tool! 

tool set prefix 51 
Get Dltem Value function 197 
GetNewDltem 

function 193, 205. 219, 245, 257 
template 205 
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CrtNewlD function 278. 293 
GetNcwModalDialog 
function 193. 257 
template 208 
GelNexlEvent function 401 
GetVector function 283-84 
Guidelines. Human Interface 115. 191. 

1-83 
handle 99 
header files 67 

HEARTBEAT.ASM program 301-5 
HeartBeat task manager 299-301 
HideDltem function 229 
Human Interface Guidelines 115, 191, 

371-83 
icons 
alert 21 1 
defining 225-28 
InsertMenu function 121-23, 135-36 

rtMltem function 135-36 
interrupts 271-307 
abort 276 
action of 276-77 
Apple II-.-. types of 273-76 
enabling and disabling 287-88 
handler 272. 277-282, 287-96 
keyboard 298-99 
maskable 274-75 
nonmaskable 275 
ProDOS 16 and 284-86 
port and 273 
ue 275 
sources, clearing 297-98 
vectors 282-84 
IntSource function 287. 298 
Is Dial ogE vent furtCtiC 
ItemColor dialog box parameter 198 
ItemDescT dialog box parameter 196-98 
ItemFlag dialog bo\ parameter 198 
item flags, setting 130-31 
item handlers 126-27 
Item ID, as index 126 
ItemID dialog box parameter 193-94 _ 
liemRect dialog box parameter 194-95 
items 

check box 249 
Push Button 246 
radio button 252-53 
• . : bar 254-56 
ItenvType dialog box parameter 1 
board Interrupts 298-99 

luivalents, programming standards 
for 378-79 
Launcher program 36-3' 
launching applications 36-37. 40-42 
load file types 41 
LoadTools function 53-54 
long word 5, 6 



machine language. See ML 
Macintosh emulation 10. 78 
macros 

in source code 73-75 
list 70 
ML 69-75 
MACNIFYNDA program 319-28 
maskable interrupt 274-75 
Mega II chip 19-20 
memory 

additional 3, 22 
addressing 20-22 
block 95-96, 104-6 
handles, reusing J 07 
management 95-11 1 
manager function list 108-1 1 
purge level 107 
relocating 98 
removing 106-7 
requesting 101-3 
memory -block record 103-4 
Memory Manager tool sel 21, 31, 52, 
95-111 
error codes 1 1 1 
starting 99 
menu 

Apple logo and 117 
bar, drawing 123-24 
bar colors 137-39 
designing 116-20 
DeskTop and 114 
flags, setting 130 
ID 1 19-20 
installing 121-23 
Hem, changing 128-30 
item, changing blink rate 137 
item, renaming 132-34 
list 116-18 
Menu Manager tool set 49, 1 14-43 

starting 121-22 
menus, programming standards for 

376-78 
menus, pull -down 113-43 
renaming 134-35 
strings and 116. 120-21 
text style, changing 133-32 
title, unhighlighling 127-28 
ML 

calling ProDOS 16 from 332 
calling Toolbox from 47-49 
modular programming 68-69 
support files and 68-75 
window naming and 159-61 
ML programs, fatal-error handler 393-95 
ModalDialog function 199. 204. 207, 208 
MODEL, ASM program 81-87 
MODEL.C program 87-90 
MODEL PAS program 90-93 
modeless dialog box, example o I use 218. 
220-25 



modem 273 

modes and resolutions, chart of 12 
modular programming. ML 68-69 
MONDO.ASM program 168-73 
C language source for 173-77 
Pascal source for 178-82 
mouse 79 

programming standards for 375-76 
MtSlartUp function 47-48 
native mode, turning on 46-47 
NDA (New Desk Accessories) 310, 
316-19 
action codes 319 
DeskTop and 316 
header 317 

requirements for 316-17 
NewDltem function 193. 202-3, 205, 

219, 226,245 
\.-w Handle function 53, 101-2, 103-4, 

278, 280-81 
NewMenu function 116, 121 
NewModalDialog function 201-2. 207 
NewModelessDialog function 219 

parameters 219-20 
NewWindow function 146-47, 149 
nonmaskable interrupt 275 
NoteAlert function 21 1 
NUMCONV.CDA program 313-16 
older chips, emulation of 17-19 
opening window 149-53 
operating system, ProDOS 16 22-23 
panic button program examples 260-64 
parameter list. ProDOS call 336-38 
parameters, window record 153-56 
parameter tables, ProDOS calls 338-44 
permanent initialization files 32 
planning for dialog boxes 191-93 
port address, window 147 
ProDOS 8 operating system 22-23, 
330-31 
booting 28-30 
ProDOS 16 operating system 22-23, 
329-67 
assembler macros and 332 
booting 30-33. .1.11 
calling 333-32 

calling from C and Pascal 332-34 
calling from ML 332 
call parameter list 336-38 
calls, list of 338-44 
• alls parameter tables 338-44 
disk contents 33-35 
errors and 334-35, 397-98 
filenames 160 
functions 335-36 
interrupts and 284-86 
Kernel Relocator 29 
Quit function 37-38 
program, relocatable 40 
program ID 39 
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programming hints, language-specific 
61-75 


software interrupt 275 
sound 14-16 


programming standards 


programming standards for 381-82 


for color 382-83 


spelling checker 218 


for dialog boxes 380-81 


Standard File Operations tool set 330, 


far key equivalents 378-79 


344-50 


lor menus jve-ro 


Mill, Jill J^. UlipiflMUU . 1 10 


tor mouse 375-76 


startup ;:<■•» Ice 26 


for sound 381-82 


Startup function, tool set 47, 51, 52-53 


programs 


status function 51-52 


how they work 25-42 


StopAlert function 211 


switching between 39-40 


strings, menus and 1 lb 


push buttons 245-49 


style bit 131 


frame style 247 


super hi res 12 14 


PushLong macro 71-73 


support file-. 6 


QuickDraw II tool set 14, 49. 259 


C and 66-67 


Quit call 39-40 


ML and 68 -75 


Quit function. ProDOS 16 37-38 


Pascal and 67-68 


quit-parameter word 39-40 
Qul1 Return Stddi 


tool set. list of 64-65 


SYSTEM/ DESK. ACCS subdirectory 310 


radio button 251-53 


system loader, Apple lies 31, 40 


colors 253 


system menu bar 1 15 


items 252-53 


! vi/TOOLS suMiiectoi 


ramdisk 22 


feskMasiei 80. 114, 124-26, 148-49. 


Rm Hoc Handle function 107 


152. 218, 405 7 


"rtfttlOtial" approach of book -1 


template, dialog 198 


relocatable code 278 


temporary initialization files 32-33 


reply record 348 


terminal program 132 


requirements for 


text style, menu, changing 131-32 


APW assembler 68 


TMl Pascal 2. 67 


.16-17 


Toolbox 3, 43-59 


starting Control Manager 243 


calling 47-49 


using book 2 


calling from ML 47-49 


reset function 51 


closing 56-57 


reset interrupt 275 


errors returned from 398-400 


screen, secret memory location ol 10, 13 


functions, errors and 55-56 


scroll Kir 254 59 


importance of using 10 


edit lines 257 


starting 46-47 


sectoi 


Tool Locator 330 


serial port, interrupts and 273 


tools, disk-based 44 


SetBarColors furvec- 


tool set 44 


SetDltemValue function 197 


function list, menu 139-43 


SetHeartBeat function 300 


interdependences 49-50 


SetMenuFlag function 130 


too] sets 


SetMenu Title function 135 


disk 53-55 


SetMJtemBLink function 137 


list of 4^ 384 


SelMllemFlag function 130-31 


order in which to start 49-50 


SeiMltem function 133 


, • 


SetMUemName function 1 


TV.C program 385-90 


Sei Vector function 282- n 1, 293, 298 


tvpe styles 1 1 1 * 


SFAHCaps function 349 


UCSD Pascal 67 


SFCetFile function 345-48 


Kl SD 99-101 


SFPutFile function 348-49 


• tool set 385 


ShowDItem function 22s> 


Version function 51 


ShutDown function 51 


VGC (Video Graphics Controller! chip 


65816 chip 17 


11-12 
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musical 15 
wCofor parameter, window record 162 
wContDeffroc 165-66 
.45-85 
closing 151-52 
color in 162-65 
contents 165-66 
controls and 244-45 



controls in 147-48 
naming 159-62 
opening 149-51 

152-59, 162 
Window Manager 80, 145-66 
starting 146 
15. 6 
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Programming 
the Apple IIGS Toolbox 

^ramming 1 the IpplellGS Tooll 

\ ides you "with the golden key 10 programming ihc Apple ll< IS. Kare is 
The programming book thai can claim to be both solidly packed with 
information and well written. This is one of those books. 

Written by recognized IIG5 authorities Morgan Davis and Dan 
Gookin, Advanced Programming Techniques 'ple-HGS To 

box delves into the intricacies of the powerful set of libraries known 
collectively as the Toolbox. You'll appreciate the equal treat! 
given to machine language, Pascal, and t and the organization that al- 

sou to come to the book with a specific problem and leave with a 
realistic solution. 

Here arejusi .1 few things you'll find ia Idvanced Programming 
Techniques for the Apple I iGS | 

• Many programming examples 

• DeskTop programs 
■ Icons 

• Interrupts 

• ProDOS 16 

• Human Interlace ( iuideJ 

idvanced Programming Technique Ippie IIGS Took 

the librar) ol vital programming data that will earn its place next to 
your this time and again. 

$19.95 




